superlab 0.1.7 → 0.1.8

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: [
@@ -27,33 +30,20 @@ const ASSET_GROUPS = {
       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,13 +433,14 @@ 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-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"),
@@ -280,6 +448,7 @@ function localizeInstalledAssets(targetDir, lang) {
     path.join(".codex", "prompts", "lab-report.md"),
     path.join(".codex", "prompts", "lab-write.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 +457,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 +499,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 +530,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/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.

package/package-assets/shared/{templates → lab/.managed/templates}/design.md

@@ -3,7 +3,7 @@
 ## Lab Change
 
 - Change id:
-- Target path: `.superlab/changes/<change-id>/design.md`
+- Target path: `.lab/changes/<change-id>/design.md`
 
 ## Research Approach
 
@@ -29,5 +29,5 @@ Describe the method and why it is plausible.
 
 ## Change Links
 
-- Spec path: `.superlab/changes/<change-id>/spec.md`
-- Tasks path: `.superlab/changes/<change-id>/tasks.md`
+- Spec path: `.lab/changes/<change-id>/spec.md`
+- Tasks path: `.lab/changes/<change-id>/tasks.md`

package/package-assets/shared/lab/.managed/templates/framing.md

@@ -0,0 +1,66 @@
+# Paper Framing
+
+## Target
+
+- Scope:
+- Current paper-facing problem:
+- Evidence boundary:
+
+## Canonical Terminology Audit
+
+- Standard terms we should reuse:
+- Adapted terms we can justify:
+- Newly coined terms that need caution:
+- Objects that must be explicit:
+- Terms to avoid:
+
+## Candidate Framing Packs
+
+### Option 1
+
+- Paper title:
+- Method name:
+- Short name or acronym:
+- Module names:
+- Contribution bullets:
+- Why this works:
+- Risks:
+
+### Option 2
+
+- Paper title:
+- Method name:
+- Short name or acronym:
+- Module names:
+- Contribution bullets:
+- Why this works:
+- Risks:
+
+### Option 3
+
+- Paper title:
+- Method name:
+- Short name or acronym:
+- Module names:
+- Contribution bullets:
+- Why this works:
+- Risks:
+
+## Recommended Framing Pack
+
+- Paper title:
+- Method name:
+- Short name or acronym:
+- Module names:
+- Contribution bullets:
+
+## Forbidden Claims And Terms
+
+- Claims to avoid:
+- Terms to avoid:
+- Why:
+
+## Approval Gate
+
+- Approved framing:
+- Open wording issues before `/lab:write`:

package/package-assets/shared/{templates → lab/.managed/templates}/paper-plan.md

@@ -5,6 +5,7 @@
 - Venue or audience:
 - Paper status:
 - Core story in one sentence:
+- Approved framing artifact:
 - Terminology lock:
 
 ## Section Status