superlab 0.1.7 → 0.1.9

package/lib/install.cjs

@@ -5,6 +5,9 @@ const { getLocalizedContent } = require("./i18n.cjs");
 
 const REPO_ROOT = path.resolve(__dirname, "..");
 const PACKAGE_VERSION = require(path.join(REPO_ROOT, "package.json")).version;
+const LAYOUT_VERSION = 1;
+const SUPERLAB_START = "<!-- superlab:start -->";
+const SUPERLAB_END = "<!-- superlab:end -->";
 
 const ASSET_GROUPS = {
   codex: [
@@ -19,41 +22,28 @@ const ASSET_GROUPS = {
   ],
   claude: [
     {
-      from: path.join(REPO_ROOT, "package-assets", "claude", "commands", "lab"),
-      to: path.join(".claude", "commands", "lab"),
+      from: path.join(REPO_ROOT, "package-assets", "claude", "commands"),
+      to: path.join(".claude", "commands"),
     },
     {
       from: path.join(REPO_ROOT, "package-assets", "shared", "skills", "lab"),
       to: path.join(".claude", "skills", "lab"),
     },
   ],
-  shared: [
-    {
-      from: path.join(REPO_ROOT, "package-assets", "shared", "templates"),
-      to: path.join(".superlab", "templates"),
-    },
-    {
-      from: path.join(REPO_ROOT, "package-assets", "shared", "config"),
-      to: path.join(".superlab", "config"),
-    },
-    {
-      from: path.join(REPO_ROOT, "package-assets", "shared", "changes"),
-      to: path.join(".superlab", "changes"),
-    },
-    {
-      from: path.join(REPO_ROOT, "package-assets", "shared", "scripts"),
-      to: path.join(".superlab", "scripts"),
-    },
-    {
-      from: path.join(REPO_ROOT, "package-assets", "shared", "examples"),
-      to: path.join(".superlab", "examples"),
-    },
-    {
-      from: path.join(REPO_ROOT, "package-assets", "shared", "context"),
-      to: path.join(".superlab", "context"),
-    },
-  ],
 };
+const LAB_SOURCE_ROOT = path.join(REPO_ROOT, "package-assets", "shared", "lab");
+const PROJECT_OWNED_LOCALIZED_PATHS = [
+  path.join(".lab", "config", "workflow.json"),
+  path.join(".lab", "context", "mission.md"),
+  path.join(".lab", "context", "state.md"),
+  path.join(".lab", "context", "decisions.md"),
+  path.join(".lab", "context", "evidence-index.md"),
+  path.join(".lab", "context", "open-questions.md"),
+  path.join(".lab", "context", "terminology-lock.md"),
+  path.join(".lab", "context", "summary.md"),
+  path.join(".lab", "context", "next-action.md"),
+  path.join(".lab", "context", "session-brief.md"),
+];
 
 function listFiles(dir) {
   const entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -92,8 +82,90 @@ function copyDirectory(sourceDir, targetDir, force) {
   fs.cpSync(sourceDir, targetDir, { recursive: true, force });
 }
 
+function copyMissingTree(sourceDir, targetDir) {
+  if (!fs.existsSync(sourceDir)) {
+    return;
+  }
+  fs.mkdirSync(targetDir, { recursive: true });
+  for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+    if (entry.isDirectory()) {
+      copyMissingTree(sourcePath, targetPath);
+      continue;
+    }
+    if (!fs.existsSync(targetPath)) {
+      fs.copyFileSync(sourcePath, targetPath);
+    }
+  }
+}
+
+function mergeJsonFile(defaultPath, targetPath) {
+  const defaults = JSON.parse(fs.readFileSync(defaultPath, "utf8"));
+  let existing = {};
+  if (fs.existsSync(targetPath)) {
+    existing = JSON.parse(fs.readFileSync(targetPath, "utf8"));
+  }
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.writeFileSync(targetPath, JSON.stringify({ ...defaults, ...existing }, null, 2) + "\n");
+}
+
+function installLabAssets(targetDir, force) {
+  copyMissingTree(path.join(LAB_SOURCE_ROOT, "system"), path.join(targetDir, ".lab", "system"));
+  copyMissingTree(path.join(LAB_SOURCE_ROOT, "context"), path.join(targetDir, ".lab", "context"));
+  copyMissingTree(path.join(LAB_SOURCE_ROOT, "changes"), path.join(targetDir, ".lab", "changes"));
+  mergeJsonFile(
+    path.join(LAB_SOURCE_ROOT, "config", "workflow.json"),
+    path.join(targetDir, ".lab", "config", "workflow.json")
+  );
+  copyDirectory(
+    path.join(LAB_SOURCE_ROOT, ".managed"),
+    path.join(targetDir, ".lab", ".managed"),
+    force
+  );
+}
+
+function coreTemplateContent(lang) {
+  return (
+    getLocalizedContent(path.join(".lab", "system", "core.md"), lang) ||
+    fs.readFileSync(path.join(LAB_SOURCE_ROOT, "system", "core.md"), "utf8")
+  );
+}
+
+function writeManagedCoreFile(targetDir, lang, { force = false } = {}) {
+  const filePath = path.join(targetDir, ".lab", "system", "core.md");
+  const managedBody = coreTemplateContent(lang);
+
+  ensureParentDir(filePath);
+  if (!fs.existsSync(filePath)) {
+    fs.writeFileSync(filePath, managedShimBlock(managedBody));
+    return;
+  }
+
+  const existing = fs.readFileSync(filePath, "utf8");
+  const start = existing.indexOf(SUPERLAB_START);
+  const end = existing.indexOf(SUPERLAB_END);
+  if (start >= 0 && end >= 0 && end >= start) {
+    upsertManagedBlock(filePath, managedBody, { force });
+    return;
+  }
+
+  const canonicalVariants = ["en", "zh"].map((candidateLang) => coreTemplateContent(candidateLang).trim());
+  if (!existing.trim() || canonicalVariants.includes(existing.trim())) {
+    fs.writeFileSync(filePath, managedShimBlock(managedBody));
+    return;
+  }
+
+  if (force) {
+    fs.writeFileSync(filePath, `${existing.trimEnd()}\n\n${managedShimBlock(managedBody)}`);
+    return;
+  }
+
+  throw new Error(`${filePath} already exists. Re-run with --force to overwrite.`);
+}
+
 function chmodScripts(targetDir) {
-  const scriptsDir = path.join(targetDir, ".superlab", "scripts");
+  const scriptsDir = path.join(targetDir, ".lab", ".managed", "scripts");
   if (!fs.existsSync(scriptsDir)) {
     return;
   }
@@ -116,7 +188,7 @@ function registryFilePath({ env = process.env } = {}) {
 }
 
 function installMetadataPath(targetDir) {
-  return path.join(targetDir, ".superlab", "install.json");
+  return path.join(targetDir, ".lab", ".managed", "install.json");
 }
 
 function ensureParentDir(filePath) {
@@ -137,6 +209,93 @@ function readProjectInstallMetadata(targetDir) {
   return JSON.parse(fs.readFileSync(filePath, "utf8"));
 }
 
+function managedShimBlock(content) {
+  return `${SUPERLAB_START}\n${content.trimEnd()}\n${SUPERLAB_END}\n`;
+}
+
+function upsertManagedBlock(filePath, body, { force = false } = {}) {
+  const block = managedShimBlock(body);
+  if (!fs.existsSync(filePath)) {
+    fs.writeFileSync(filePath, block);
+    return;
+  }
+
+  const existing = fs.readFileSync(filePath, "utf8");
+  const start = existing.indexOf(SUPERLAB_START);
+  const end = existing.indexOf(SUPERLAB_END);
+
+  if (start >= 0 && end >= 0 && end >= start) {
+    const updated =
+      existing.slice(0, start) +
+      block +
+      existing.slice(end + SUPERLAB_END.length).replace(/^\n/, "");
+    fs.writeFileSync(filePath, updated);
+    return;
+  }
+
+  if (force) {
+    fs.writeFileSync(filePath, `${existing.trimEnd()}\n\n${block}`);
+    return;
+  }
+
+  throw new Error(`${filePath} already exists. Re-run with --force to overwrite.`);
+}
+
+function agentsShim(lang) {
+  if (lang === "zh") {
+    return `# Project Agent Notes
+
+本仓库使用项目级 \`.lab/\` 研究工作流。
+
+如果任务属于 research、experiment、report 或 paper-writing：
+1. 先读 \`.lab/system/core.md\`
+2. 再读 \`.lab/context/session-brief.md\`
+
+不要静默覆盖 \`.lab/context/*\`。
+非研究类工程任务不要强行进入 \`/lab:*\`。`;
+  }
+
+  return `# Project Agent Notes
+
+This repository uses a project-level \`.lab/\` research workflow.
+
+For research, experiment, reporting, or paper-writing tasks:
+1. Read \`.lab/system/core.md\`
+2. Then read \`.lab/context/session-brief.md\`
+
+Do not silently overwrite \`.lab/context/*\`.
+For non-research engineering tasks, do not force \`/lab:*\`.`;
+}
+
+function claudeShim(lang) {
+  if (lang === "zh") {
+    return `# Claude Project Notes
+
+本仓库使用项目级 \`.lab/\` 研究工作流。
+
+@.lab/system/core.md
+@.lab/context/session-brief.md
+
+不要静默覆盖 \`.lab/context/*\`。
+非研究类工程任务不要强行进入 \`/lab:*\`。`;
+  }
+
+  return `# Claude Project Notes
+
+This repository uses a project-level \`.lab/\` research workflow.
+
+@.lab/system/core.md
+@.lab/context/session-brief.md
+
+Do not silently overwrite \`.lab/context/*\`.
+For non-research engineering tasks, do not force \`/lab:*\`.`;
+}
+
+function writePlatformShims(targetDir, lang, force) {
+  upsertManagedBlock(path.join(targetDir, "AGENTS.md"), agentsShim(lang), { force });
+  upsertManagedBlock(path.join(targetDir, "CLAUDE.md"), claudeShim(lang), { force });
+}
+
 function detectLegacyPlatform(targetDir) {
   const hasCodex =
     fs.existsSync(path.join(targetDir, ".codex", "prompts")) ||
@@ -162,8 +321,14 @@ function looksChinese(text) {
 }
 
 function detectLegacyLanguage(targetDir) {
-  const workflowConfigPath = path.join(targetDir, ".superlab", "config", "workflow.json");
-  if (fs.existsSync(workflowConfigPath)) {
+  const workflowConfigPaths = [
+    path.join(targetDir, ".lab", "config", "workflow.json"),
+    path.join(targetDir, ".superlab", "config", "workflow.json"),
+  ];
+  for (const workflowConfigPath of workflowConfigPaths) {
+    if (!fs.existsSync(workflowConfigPath)) {
+      continue;
+    }
     try {
       const config = JSON.parse(fs.readFileSync(workflowConfigPath, "utf8"));
       if (config.workflow_language === "zh" || config.workflow_language === "en") {
@@ -177,6 +342,7 @@ function detectLegacyLanguage(targetDir) {
   const probeFiles = [
     path.join(targetDir, ".codex", "prompts", "lab-idea.md"),
     path.join(targetDir, ".claude", "commands", "lab", "idea.md"),
+    path.join(targetDir, ".lab", ".managed", "templates", "idea.md"),
     path.join(targetDir, ".superlab", "templates", "idea.md"),
   ];
 
@@ -203,6 +369,7 @@ function detectLegacyInstallMetadata(targetDir) {
     lang: detectLegacyLanguage(targetDir),
     package_version: "legacy",
     updated_at: null,
+    layout_version: 0,
     legacy: true,
   };
 }
@@ -266,20 +433,24 @@ function detectLanguage({ explicitLang, env = process.env } = {}) {
   return locale.includes("zh") ? "zh" : "en";
 }
 
-function localizeInstalledAssets(targetDir, lang) {
+function localizeInstalledAssets(targetDir, lang, { newlyCreatedProjectOwnedPaths = new Set() } = {}) {
   if (lang !== "zh") {
     return;
   }
 
   const relativePaths = [
+    path.join(".codex", "prompts", "lab.md"),
     path.join(".codex", "prompts", "lab-idea.md"),
+    path.join(".codex", "prompts", "lab-framing.md"),
     path.join(".codex", "prompts", "lab-spec.md"),
     path.join(".codex", "prompts", "lab-run.md"),
     path.join(".codex", "prompts", "lab-iterate.md"),
     path.join(".codex", "prompts", "lab-review.md"),
     path.join(".codex", "prompts", "lab-report.md"),
     path.join(".codex", "prompts", "lab-write.md"),
+    path.join(".claude", "commands", "lab.md"),
     path.join(".claude", "commands", "lab", "idea.md"),
+    path.join(".claude", "commands", "lab", "framing.md"),
     path.join(".claude", "commands", "lab", "spec.md"),
     path.join(".claude", "commands", "lab", "run.md"),
     path.join(".claude", "commands", "lab", "iterate.md"),
@@ -288,27 +459,36 @@ function localizeInstalledAssets(targetDir, lang) {
     path.join(".claude", "commands", "lab", "write.md"),
     path.join(".codex", "skills", "lab", "SKILL.md"),
     path.join(".codex", "skills", "lab", "stages", "idea.md"),
+    path.join(".codex", "skills", "lab", "stages", "framing.md"),
+    path.join(".codex", "skills", "lab", "stages", "spec.md"),
+    path.join(".codex", "skills", "lab", "stages", "run.md"),
+    path.join(".codex", "skills", "lab", "stages", "iterate.md"),
+    path.join(".codex", "skills", "lab", "stages", "review.md"),
+    path.join(".codex", "skills", "lab", "stages", "report.md"),
     path.join(".codex", "skills", "lab", "stages", "write.md"),
+    path.join(".codex", "skills", "lab", "references", "workflow.md"),
     path.join(".claude", "skills", "lab", "SKILL.md"),
     path.join(".claude", "skills", "lab", "stages", "idea.md"),
+    path.join(".claude", "skills", "lab", "stages", "framing.md"),
+    path.join(".claude", "skills", "lab", "stages", "spec.md"),
+    path.join(".claude", "skills", "lab", "stages", "run.md"),
+    path.join(".claude", "skills", "lab", "stages", "iterate.md"),
+    path.join(".claude", "skills", "lab", "stages", "review.md"),
+    path.join(".claude", "skills", "lab", "stages", "report.md"),
     path.join(".claude", "skills", "lab", "stages", "write.md"),
-    path.join(".superlab", "templates", "idea.md"),
-    path.join(".superlab", "templates", "proposal.md"),
-    path.join(".superlab", "templates", "design.md"),
-    path.join(".superlab", "templates", "spec.md"),
-    path.join(".superlab", "templates", "tasks.md"),
-    path.join(".superlab", "templates", "iteration-report.md"),
-    path.join(".superlab", "templates", "review-checklist.md"),
-    path.join(".superlab", "templates", "final-report.md"),
-    path.join(".superlab", "templates", "paper-plan.md"),
-    path.join(".superlab", "templates", "paper-section.md"),
-    path.join(".superlab", "templates", "write-iteration.md"),
-    path.join(".superlab", "config", "workflow.json"),
-    path.join(".superlab", "context", "mission.md"),
-    path.join(".superlab", "context", "state.md"),
-    path.join(".superlab", "context", "decisions.md"),
-    path.join(".superlab", "context", "evidence-index.md"),
-    path.join(".superlab", "context", "open-questions.md"),
+    path.join(".claude", "skills", "lab", "references", "workflow.md"),
+    path.join(".lab", ".managed", "templates", "idea.md"),
+    path.join(".lab", ".managed", "templates", "framing.md"),
+    path.join(".lab", ".managed", "templates", "proposal.md"),
+    path.join(".lab", ".managed", "templates", "design.md"),
+    path.join(".lab", ".managed", "templates", "spec.md"),
+    path.join(".lab", ".managed", "templates", "tasks.md"),
+    path.join(".lab", ".managed", "templates", "iteration-report.md"),
+    path.join(".lab", ".managed", "templates", "review-checklist.md"),
+    path.join(".lab", ".managed", "templates", "final-report.md"),
+    path.join(".lab", ".managed", "templates", "paper-plan.md"),
+    path.join(".lab", ".managed", "templates", "paper-section.md"),
+    path.join(".lab", ".managed", "templates", "write-iteration.md"),
   ];
 
   for (const relativePath of relativePaths) {
@@ -321,6 +501,20 @@ function localizeInstalledAssets(targetDir, lang) {
       fs.writeFileSync(absolutePath, localized);
     }
   }
+
+  for (const relativePath of PROJECT_OWNED_LOCALIZED_PATHS) {
+    if (!newlyCreatedProjectOwnedPaths.has(relativePath)) {
+      continue;
+    }
+    const localized = getLocalizedContent(relativePath, lang);
+    if (!localized) {
+      continue;
+    }
+    const absolutePath = path.join(targetDir, relativePath);
+    if (fs.existsSync(absolutePath)) {
+      fs.writeFileSync(absolutePath, localized);
+    }
+  }
 }
 
 function installSuperlab({
@@ -338,19 +532,25 @@ function installSuperlab({
   if (platform === "claude" || platform === "both") {
     groups.push(...ASSET_GROUPS.claude);
   }
-  groups.push(...ASSET_GROUPS.shared);
 
+  const resolvedLang = detectLanguage({ explicitLang: lang, env });
+  const newlyCreatedProjectOwnedPaths = new Set(
+    PROJECT_OWNED_LOCALIZED_PATHS.filter((relativePath) => !fs.existsSync(path.join(targetDir, relativePath)))
+  );
   for (const asset of groups) {
     copyDirectory(asset.from, path.join(targetDir, asset.to), force);
   }
-  const resolvedLang = detectLanguage({ explicitLang: lang, env });
-  localizeInstalledAssets(targetDir, resolvedLang);
+  installLabAssets(targetDir, force);
+  writePlatformShims(targetDir, resolvedLang, force);
+  writeManagedCoreFile(targetDir, resolvedLang, { force });
+  localizeInstalledAssets(targetDir, resolvedLang, { newlyCreatedProjectOwnedPaths });
   chmodScripts(targetDir);
   const metadata = {
     target_dir: path.resolve(targetDir),
     platform,
     lang: resolvedLang,
     package_version: PACKAGE_VERSION,
+    layout_version: LAYOUT_VERSION,
     updated_at: new Date().toISOString(),
   };
   writeProjectInstallMetadata(targetDir, metadata);

package/package-assets/claude/commands/lab/framing.md

@@ -0,0 +1,11 @@
+---
+name: "LAB: Framing"
+description: Lock paper-facing naming, title, and contribution framing before drafting
+category: Workflow
+tags: [workflow, research, framing]
+---
+
+Use the installed `lab` skill at `.claude/skills/lab/SKILL.md`.
+
+Execute the requested `/lab:framing` stage against the user's argument now. Do not only recommend another lab stage. If a blocking prerequisite is missing, say exactly what is missing and ask at most one clarifying question.
+This command runs the `/lab:framing` stage. Follow the installed skill, stage guide, and the project assets under `.lab/`.

package/package-assets/claude/commands/lab/idea.md

@@ -7,4 +7,5 @@ tags: [workflow, research, idea]
 
 Use the installed `lab` skill at `.claude/skills/lab/SKILL.md`.
 
-This command runs the `/lab:idea` stage. Follow the installed skill, stage guide, templates, and scripts under `.superlab/`.
+Execute the requested `/lab:idea` stage against the user's argument now. Do not only recommend another lab stage. If a blocking prerequisite is missing, say exactly what is missing and ask at most one clarifying question.
+This command runs the `/lab:idea` stage. Follow the installed skill, stage guide, and the project assets under `.lab/`.

package/package-assets/claude/commands/lab/iterate.md

@@ -7,4 +7,5 @@ tags: [workflow, research, iterate]
 
 Use the installed `lab` skill at `.claude/skills/lab/SKILL.md`.
 
-This command runs the `/lab:iterate` stage. Follow the installed skill, stage guide, templates, and scripts under `.superlab/`.
+Execute the requested `/lab:iterate` stage against the user's argument now. Do not only recommend another lab stage. If a blocking prerequisite is missing, say exactly what is missing and ask at most one clarifying question.
+This command runs the `/lab:iterate` stage. Follow the installed skill, stage guide, and the project assets under `.lab/`.

package/package-assets/claude/commands/lab/report.md

@@ -7,4 +7,5 @@ tags: [workflow, research, report]
 
 Use the installed `lab` skill at `.claude/skills/lab/SKILL.md`.
 
-This command runs the `/lab:report` stage. Follow the installed skill, stage guide, templates, and scripts under `.superlab/`.
+Execute the requested `/lab:report` stage against the user's argument now. Do not only recommend another lab stage. If a blocking prerequisite is missing, say exactly what is missing and ask at most one clarifying question.
+This command runs the `/lab:report` stage. Follow the installed skill, stage guide, and the project assets under `.lab/`.

package/package-assets/claude/commands/lab/review.md

@@ -7,4 +7,5 @@ tags: [workflow, research, review]
 
 Use the installed `lab` skill at `.claude/skills/lab/SKILL.md`.
 
-This command runs the `/lab:review` stage. Follow the installed skill, stage guide, templates, and scripts under `.superlab/`.
+Execute the requested `/lab:review` stage against the user's argument now. Do not only recommend another lab stage. If a blocking prerequisite is missing, say exactly what is missing and ask at most one clarifying question.
+This command runs the `/lab:review` stage. Follow the installed skill, stage guide, and the project assets under `.lab/`.

package/package-assets/claude/commands/lab/run.md

@@ -7,4 +7,5 @@ tags: [workflow, research, run]
 
 Use the installed `lab` skill at `.claude/skills/lab/SKILL.md`.
 
-This command runs the `/lab:run` stage. Follow the installed skill, stage guide, templates, and scripts under `.superlab/`.
+Execute the requested `/lab:run` stage against the user's argument now. Do not only recommend another lab stage. If a blocking prerequisite is missing, say exactly what is missing and ask at most one clarifying question.
+This command runs the `/lab:run` stage. Follow the installed skill, stage guide, and the project assets under `.lab/`.

package/package-assets/claude/commands/lab/spec.md

@@ -7,4 +7,5 @@ tags: [workflow, research, spec]
 
 Use the installed `lab` skill at `.claude/skills/lab/SKILL.md`.
 
-This command runs the `/lab:spec` stage. Follow the installed skill, stage guide, templates, and scripts under `.superlab/`.
+Execute the requested `/lab:spec` stage against the user's argument now. Do not only recommend another lab stage. If a blocking prerequisite is missing, say exactly what is missing and ask at most one clarifying question.
+This command runs the `/lab:spec` stage. Follow the installed skill, stage guide, and the project assets under `.lab/`.

package/package-assets/claude/commands/lab/write.md

@@ -7,4 +7,5 @@ tags: [workflow, research, writing]
 
 Use the installed `lab` skill at `.claude/skills/lab/SKILL.md`.
 
-This command runs the `/lab:write` stage. It must read the matching section reference from `.claude/skills/lab/references/paper-writing/`, plus `paper-review.md` and `does-my-writing-flow-source.md`, build a mini-outline, and then revise only one section.
+Execute the requested `/lab:write` stage against the user's argument now. Do not only recommend another lab stage. If a blocking prerequisite is missing, say exactly what is missing and ask at most one clarifying question.
+This command runs the `/lab:write` stage. It requires an approved framing artifact from `/lab:framing`, must read the matching section reference from `.claude/skills/lab/references/paper-writing/`, plus `paper-review.md` and `does-my-writing-flow-source.md`, build a mini-outline, and then revise only one section.

package/package-assets/claude/commands/lab.md

@@ -0,0 +1,48 @@
+---
+name: "LAB"
+description: Overview of the /lab research workflow and stage selection
+category: Workflow
+tags: [workflow, research, overview]
+---
+
+# `/lab` for Claude
+
+`/lab` is a strict research workflow command family. Use the same repository artifacts and stage boundaries every time.
+
+## Subcommands
+
+- `/lab:idea`
+  Research the idea, define the problem and failure case, classify the contribution and breakthrough level, compare against existing methods, end with three meaningful points, and keep an explicit approval gate before any implementation.
+
+- `/lab:framing`
+  Lock paper-facing method name, module names, paper title, and contribution bullets by auditing current-field and adjacent-field terminology, then keep an approval gate before any section drafting.
+
+- `/lab:spec`
+  Convert the approved idea into one lab change directory under `.lab/changes/<change-id>/`, then draft `proposal`, `design`, `spec`, and `tasks` inside that directory.
+
+- `/lab:run`
+  Execute the smallest useful validation run, register it, and produce the first normalized evaluation summary.
+
+- `/lab:iterate`
+  Run bounded Ralph Wiggum style experiment loops with a frozen mission, explicit thresholds, deterministic verification commands, `completion_promise`, and per-round reports.
+
+- `/lab:review`
+  Audit documents or results in reviewer mode. Start with a short summary, then output findings, fatal flaws, fix priority, and residual risks.
+
+- `/lab:report`
+  Generate the final research report from accumulated runs and iteration artifacts.
+
+- `/lab:write`
+  Turn stable report artifacts into paper sections through small, evidence-bound writing rounds using the vendored paper-writing references under the installed `lab` skill.
+
+## Dispatch Rules
+
+- Always use `skills/lab/SKILL.md` as the workflow contract.
+- When the user explicitly invokes `/lab:<stage>`, execute that stage now against the provided argument instead of only recommending another `/lab` stage.
+- Start by giving the user a concise summary, then decide whether to write artifacts, then report the output path and next step.
+- When ambiguity matters, ask one clarifying question at a time; when multiple paths are viable, present 2-3 approaches before converging.
+- `/lab:spec` is not complete until the approved change is frozen under `.lab/changes/<change-id>/`.
+- Never skip directly from `/lab:idea` to code.
+- `/lab:iterate` requires a normalized summary from `scripts/eval_report.py`.
+- `/lab:write` requires an approved framing artifact from `/lab:framing`.
+- `/lab:write` requires stable report artifacts, a mini-outline, the active section guide, `paper-review.md`, and `does-my-writing-flow-source.md`, and should only change one section per round.

package/package-assets/codex/prompts/lab-framing.md

@@ -0,0 +1,9 @@
+---
+description: Lock paper-facing naming, title, and contribution framing before drafting
+argument-hint: naming, title, or contribution framing target
+---
+
+Use the installed `lab` skill at `.codex/skills/lab/SKILL.md`.
+
+Execute the requested `/lab:framing` stage against the user's argument now. Do not only recommend another lab stage. If a blocking prerequisite is missing, say exactly what is missing and ask at most one clarifying question.
+This command runs the `/lab:framing` stage. Follow the installed skill, stage guide, and the project assets under `.lab/`.

package/package-assets/codex/prompts/lab-idea.md

@@ -5,4 +5,5 @@ argument-hint: idea or research problem
 
 Use the installed `lab` skill at `.codex/skills/lab/SKILL.md`.
 
-This command runs the `/lab:idea` stage. Follow the installed skill, stage guide, templates, and scripts under `.superlab/`.
+Execute the requested `/lab:idea` stage against the user's argument now. Do not only recommend another lab stage. If a blocking prerequisite is missing, say exactly what is missing and ask at most one clarifying question.
+This command runs the `/lab:idea` stage. Follow the installed skill, stage guide, and the project assets under `.lab/`.

package/package-assets/codex/prompts/lab-iterate.md

@@ -5,4 +5,5 @@ argument-hint: iteration mission
 
 Use the installed `lab` skill at `.codex/skills/lab/SKILL.md`.
 
-This command runs the `/lab:iterate` stage. Follow the installed skill, stage guide, templates, and scripts under `.superlab/`.
+Execute the requested `/lab:iterate` stage against the user's argument now. Do not only recommend another lab stage. If a blocking prerequisite is missing, say exactly what is missing and ask at most one clarifying question.
+This command runs the `/lab:iterate` stage. Follow the installed skill, stage guide, and the project assets under `.lab/`.

package/package-assets/codex/prompts/lab-report.md

@@ -5,4 +5,5 @@ argument-hint: report context
 
 Use the installed `lab` skill at `.codex/skills/lab/SKILL.md`.
 
-This command runs the `/lab:report` stage. Follow the installed skill, stage guide, templates, and scripts under `.superlab/`.
+Execute the requested `/lab:report` stage against the user's argument now. Do not only recommend another lab stage. If a blocking prerequisite is missing, say exactly what is missing and ask at most one clarifying question.
+This command runs the `/lab:report` stage. Follow the installed skill, stage guide, and the project assets under `.lab/`.

package/package-assets/codex/prompts/lab-review.md

@@ -5,4 +5,5 @@ argument-hint: artifact or result to review
 
 Use the installed `lab` skill at `.codex/skills/lab/SKILL.md`.
 
-This command runs the `/lab:review` stage. Follow the installed skill, stage guide, templates, and scripts under `.superlab/`.
+Execute the requested `/lab:review` stage against the user's argument now. Do not only recommend another lab stage. If a blocking prerequisite is missing, say exactly what is missing and ask at most one clarifying question.
+This command runs the `/lab:review` stage. Follow the installed skill, stage guide, and the project assets under `.lab/`.

package/package-assets/codex/prompts/lab-run.md

@@ -5,4 +5,5 @@ argument-hint: run context
 
 Use the installed `lab` skill at `.codex/skills/lab/SKILL.md`.
 
-This command runs the `/lab:run` stage. Follow the installed skill, stage guide, templates, and scripts under `.superlab/`.
+Execute the requested `/lab:run` stage against the user's argument now. Do not only recommend another lab stage. If a blocking prerequisite is missing, say exactly what is missing and ask at most one clarifying question.
+This command runs the `/lab:run` stage. Follow the installed skill, stage guide, and the project assets under `.lab/`.

package/package-assets/codex/prompts/lab-spec.md

@@ -5,4 +5,5 @@ argument-hint: approved idea context
 
 Use the installed `lab` skill at `.codex/skills/lab/SKILL.md`.
 
-This command runs the `/lab:spec` stage. Follow the installed skill, stage guide, templates, and scripts under `.superlab/`.
+Execute the requested `/lab:spec` stage against the user's argument now. Do not only recommend another lab stage. If a blocking prerequisite is missing, say exactly what is missing and ask at most one clarifying question.
+This command runs the `/lab:spec` stage. Follow the installed skill, stage guide, and the project assets under `.lab/`.

package/package-assets/codex/prompts/lab-write.md

@@ -5,4 +5,5 @@ argument-hint: section or writing target
 
 Use the installed `lab` skill at `.codex/skills/lab/SKILL.md`.
 
-This command runs the `/lab:write` stage. It must read the matching section reference from `.codex/skills/lab/references/paper-writing/`, plus `paper-review.md` and `does-my-writing-flow-source.md`, build a mini-outline, and then revise only one section.
+Execute the requested `/lab:write` stage against the user's argument now. Do not only recommend another lab stage. If a blocking prerequisite is missing, say exactly what is missing and ask at most one clarifying question.
+This command runs the `/lab:write` stage. It requires an approved framing artifact from `/lab:framing`, must read the matching section reference from `.codex/skills/lab/references/paper-writing/`, plus `paper-review.md` and `does-my-writing-flow-source.md`, build a mini-outline, and then revise only one section.