@nuucognition/flint-cli 0.5.0-alpha.1 → 0.5.1

package/dist/{chunk-67JRCBRR.js → chunk-XWUP7WHQ.js}

@@ -7,7 +7,7 @@ import {
   registerFlint,
   registerFlintByPath,
   updateFlintEntry
-} from "./chunk-O7OVKLLV.js";
+} from "./chunk-C66KJDI7.js";
 import {
   exists,
   runConcurrent
@@ -15,7 +15,7 @@ import {
 import {
   ensureMetadataDirs,
   syncSourceRepoMetadata
-} from "./chunk-PONDZIXS.js";
+} from "./chunk-M3NSYVYR.js";
 import {
   addPlateDeclaration,
   addShardToConfig,
@@ -39,18 +39,18 @@ import {
   toKebabCase,
   writeFlintJson,
   writeFlintToml
-} from "./chunk-XCVQLFHY.js";
+} from "./chunk-CBGQBE6C.js";
 
 // ../../packages/flint/dist/index.js
-import { mkdir as mkdir2, stat as stat8 } from "fs/promises";
-import { join as join10 } from "path";
+import { mkdir as mkdir2, stat as stat9 } from "fs/promises";
+import { join as join11 } from "path";
 import { stat as stat22 } from "fs/promises";
 import { dirname as dirname2, isAbsolute, join as join22 } from "path";
 import { mkdir as mkdir22, writeFile as writeFile5 } from "fs/promises";
 import { join as join32 } from "path";
 import { exec } from "child_process";
 import { promisify } from "util";
-import { readdir as readdir7, stat as stat32, access as access2 } from "fs/promises";
+import { readdir as readdir8, stat as stat32, access as access2 } from "fs/promises";
 import { join as join42, resolve } from "path";
 import { homedir } from "os";
 import { readFile as readFile5, writeFile as writeFile22, mkdir as mkdir32 } from "fs/promises";
@@ -76,7 +76,7 @@ import { rm as rm32 } from "fs/promises";
 import { execFile } from "child_process";
 import { cp as cp3, mkdir as mkdir9, readdir as readdir42, readFile as readFile6, rename as rename22, rm as rm52, stat as stat72, writeFile as writeFile7 } from "fs/promises";
 import { homedir as homedir2 } from "os";
-import { basename as basename3, dirname as dirname3, join as join11, resolve as resolve4 } from "path";
+import { basename as basename3, dirname as dirname3, join as join112, resolve as resolve4 } from "path";
 import { promisify as promisify4 } from "util";
 import { readFile as readFile52, writeFile as writeFile6, mkdir as mkdir8, rm as rm42, stat as stat62 } from "fs/promises";
 import { join as join102 } from "path";
@@ -88,7 +88,7 @@ import { parse as parseYaml4 } from "yaml";
 
 // ../../packages/flint-migrations/dist/index.js
 import { randomUUID as randomUUID2 } from "crypto";
-import { join as join9, dirname } from "path";
+import { join as join10, dirname } from "path";
 import { access, readFile as readFile4, writeFile as writeFile4, unlink, mkdir as mkdir5 } from "fs/promises";
 import { join } from "path";
 import { rename, mkdir, stat, cp, rm } from "fs/promises";
@@ -107,6 +107,8 @@ import { join as join7 } from "path";
 import { readdir as readdir5, rm as rm5, mkdir as mkdir4 } from "fs/promises";
 import { rename as rename4, readdir as readdir6, rmdir, stat as stat7 } from "fs/promises";
 import { join as join8 } from "path";
+import { join as join9 } from "path";
+import { readdir as readdir7, stat as stat8 } from "fs/promises";
 function compareVersions(a, b) {
   const partsA = a.split(".").map(Number);
   const partsB = b.split(".").map(Number);
@@ -1827,6 +1829,212 @@ var sourceReposRestructure = {
     return true;
   }
 };
+var MIGRATION_ID3 = "unify-session-tracking-0.4.0-0.5.0";
+var SESSION_FIELD_PATTERN = /^[a-z]+-sessions$/;
+var UNIFIED_FIELD = "orbh-sessions";
+async function findMarkdownFiles3(dir) {
+  const results = [];
+  try {
+    const entries = await readdir7(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join9(dir, entry.name);
+      if (entry.isDirectory()) {
+        const nested = await findMarkdownFiles3(fullPath);
+        results.push(...nested);
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
+        results.push(fullPath);
+      }
+    }
+  } catch {
+  }
+  return results;
+}
+function parseFrontmatter(content) {
+  const lines = content.split("\n");
+  if (lines[0]?.trim() !== "---") {
+    return { hasFrontmatter: false, frontmatterLines: [], bodyStart: 0 };
+  }
+  let endIndex = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i]?.trim() === "---") {
+      endIndex = i;
+      break;
+    }
+  }
+  if (endIndex === -1) {
+    return { hasFrontmatter: false, frontmatterLines: [], bodyStart: 0 };
+  }
+  return {
+    hasFrontmatter: true,
+    frontmatterLines: lines.slice(1, endIndex),
+    bodyStart: endIndex + 1
+  };
+}
+function extractSessionValues(lines, startIdx) {
+  const ids = [];
+  const keyLine = lines[startIdx];
+  const inlineMatch = keyLine.match(/:\s*\[(.+)\]\s*$/);
+  if (inlineMatch) {
+    const entries = inlineMatch[1].split(",");
+    for (const e of entries) {
+      const trimmed = e.trim().replace(/^["']|["']$/g, "");
+      if (trimmed) ids.push(trimmed);
+    }
+    return { ids, endIdx: startIdx };
+  }
+  let i = startIdx + 1;
+  while (i < lines.length) {
+    const line = lines[i];
+    const listMatch = line.match(/^\s+-\s+(.+)$/);
+    if (!listMatch) break;
+    const val = listMatch[1].trim().replace(/^["']|["']$/g, "");
+    if (val) ids.push(val);
+    i++;
+  }
+  return { ids, endIdx: i - 1 };
+}
+function rewriteFrontmatter(content) {
+  const { hasFrontmatter, frontmatterLines, bodyStart } = parseFrontmatter(content);
+  if (!hasFrontmatter) return null;
+  const lines = content.split("\n");
+  const allIds = [];
+  const linesToRemove = /* @__PURE__ */ new Set();
+  let hasOldFields = false;
+  let existingOrbhIdx = -1;
+  for (let i = 0; i < frontmatterLines.length; i++) {
+    const line = frontmatterLines[i];
+    const keyMatch = line.match(/^([a-z]+-sessions)\s*:/);
+    if (!keyMatch) continue;
+    const fieldName = keyMatch[1];
+    const { ids, endIdx } = extractSessionValues(frontmatterLines, i);
+    if (fieldName === UNIFIED_FIELD) {
+      existingOrbhIdx = i;
+      allIds.push(...ids);
+      for (let j = i; j <= endIdx; j++) {
+        linesToRemove.add(j + 1);
+      }
+    } else if (SESSION_FIELD_PATTERN.test(fieldName)) {
+      hasOldFields = true;
+      allIds.push(...ids);
+      for (let j = i; j <= endIdx; j++) {
+        linesToRemove.add(j + 1);
+      }
+    }
+  }
+  if (!hasOldFields) return null;
+  const seen = /* @__PURE__ */ new Set();
+  const uniqueIds = [];
+  for (const id of allIds) {
+    const normalized = id.trim();
+    if (normalized && !seen.has(normalized)) {
+      seen.add(normalized);
+      uniqueIds.push(normalized);
+    }
+  }
+  const newLines = ["---"];
+  let insertedOrbh = false;
+  for (let i = 1; i < bodyStart; i++) {
+    if (i === bodyStart - 1) {
+      if (!insertedOrbh && uniqueIds.length > 0) {
+        newLines.push(`${UNIFIED_FIELD}:`);
+        for (const id of uniqueIds) {
+          newLines.push(`  - "${id}"`);
+        }
+        insertedOrbh = true;
+      }
+      newLines.push(lines[i]);
+      break;
+    }
+    if (linesToRemove.has(i)) {
+      if (!insertedOrbh && uniqueIds.length > 0) {
+        newLines.push(`${UNIFIED_FIELD}:`);
+        for (const id of uniqueIds) {
+          newLines.push(`  - "${id}"`);
+        }
+        insertedOrbh = true;
+      }
+      continue;
+    }
+    newLines.push(lines[i]);
+  }
+  for (let i = bodyStart; i < lines.length; i++) {
+    newLines.push(lines[i]);
+  }
+  return newLines.join("\n");
+}
+var unifySessionTracking = {
+  id: MIGRATION_ID3,
+  name: "Unify Session Tracking",
+  description: "Merges per-runtime session fields (claude-sessions, codex-sessions) into a single orbh-sessions field",
+  from: "0.4.0",
+  to: "0.5.0",
+  async check(ctx) {
+    try {
+      await stat8(join9(ctx.flintPath, "Mesh"));
+    } catch {
+      return false;
+    }
+    const meshDir = join9(ctx.flintPath, "Mesh");
+    const files = await findMarkdownFiles3(meshDir);
+    for (const file of files) {
+      const relativePath = file.slice(ctx.flintPath.length + 1);
+      const content = await ctx.read(relativePath);
+      const result = rewriteFrontmatter(content);
+      if (result !== null) return true;
+    }
+    return false;
+  },
+  async run(ctx) {
+    const changes = [];
+    try {
+      const meshDir = join9(ctx.flintPath, "Mesh");
+      const files = await findMarkdownFiles3(meshDir);
+      let modifiedCount = 0;
+      for (const file of files) {
+        const relativePath = file.slice(ctx.flintPath.length + 1);
+        const content = await ctx.read(relativePath);
+        const rewritten = rewriteFrontmatter(content);
+        if (rewritten !== null) {
+          await ctx.write(relativePath, rewritten);
+          modifiedCount++;
+        }
+      }
+      if (modifiedCount > 0) {
+        changes.push(
+          `Merged per-runtime session fields into orbh-sessions in ${modifiedCount} file(s)`
+        );
+      } else {
+        changes.push("No files contained per-runtime session fields");
+      }
+      return { success: true, changes };
+    } catch (err) {
+      const error = err instanceof Error ? err.message : String(err);
+      ctx.error(`Migration failed: ${error}`);
+      return { success: false, changes, warnings: [`Error: ${error}`] };
+    }
+  },
+  async verify(ctx) {
+    const meshDir = join9(ctx.flintPath, "Mesh");
+    const files = await findMarkdownFiles3(meshDir);
+    for (const file of files) {
+      const relativePath = file.slice(ctx.flintPath.length + 1);
+      const content = await ctx.read(relativePath);
+      const { hasFrontmatter, frontmatterLines } = parseFrontmatter(content);
+      if (!hasFrontmatter) continue;
+      for (const line of frontmatterLines) {
+        const keyMatch = line.match(/^([a-z]+-sessions)\s*:/);
+        if (keyMatch && keyMatch[1] !== UNIFIED_FIELD) {
+          ctx.error(
+            `Verification failed: ${relativePath} still has ${keyMatch[1]}`
+          );
+          return false;
+        }
+      }
+    }
+    ctx.log("Verification passed: no per-runtime session fields remain");
+    return true;
+  }
+};
 var migrations = [
   // 0.0.0 → 0.2.0
   workspaceTomlToReferences,
@@ -1839,8 +2047,19 @@ var migrations = [
   sourcingSystem,
   // 0.3.0 → 0.4.0
   unifiedReferences,
-  sourceReposRestructure
+  sourceReposRestructure,
+  // 0.4.0 → 0.5.0
+  unifySessionTracking
 ];
+var versionStepSealed = {
+  "0.2.0": true,
+  "0.3.0": true,
+  "0.4.0": true,
+  "0.5.0": false
+};
+function isVersionStepSealed(version) {
+  return versionStepSealed[version] ?? false;
+}
 function getVersionSteps() {
   const seen = /* @__PURE__ */ new Set();
   const steps = [];
@@ -1869,28 +2088,28 @@ function createMigrationContext(flintPath, options = {}) {
     error,
     async exists(path) {
       try {
-        await access(join9(flintPath, path));
+        await access(join10(flintPath, path));
         return true;
       } catch {
         return false;
       }
     },
     async read(path) {
-      return readFile4(join9(flintPath, path), "utf-8");
+      return readFile4(join10(flintPath, path), "utf-8");
     },
     async write(path, content) {
-      const fullPath = join9(flintPath, path);
+      const fullPath = join10(flintPath, path);
       await mkdir5(dirname(fullPath), { recursive: true });
       await writeFile4(fullPath, content, "utf-8");
     },
     async delete(path) {
-      await unlink(join9(flintPath, path));
+      await unlink(join10(flintPath, path));
     }
   };
 }
 async function readFlintJson3(flintPath) {
   try {
-    const content = await readFile4(join9(flintPath, "flint.json"), "utf-8");
+    const content = await readFile4(join10(flintPath, "flint.json"), "utf-8");
     return JSON.parse(content);
   } catch (error) {
     if (error.code === "ENOENT") {
@@ -1907,7 +2126,7 @@ function createFlintJson2() {
   };
 }
 async function writeFlintJson2(flintPath, json) {
-  await writeFile4(join9(flintPath, "flint.json"), JSON.stringify(json, null, 2) + "\n");
+  await writeFile4(join10(flintPath, "flint.json"), JSON.stringify(json, null, 2) + "\n");
 }
 function ensureFlintJsonIdentity(json) {
   if (!json.id) json.id = randomUUID2();
@@ -2059,11 +2278,81 @@ async function runMigrations(flintPath, options = {}) {
       (m) => result.applied.some((a) => a.id === m.id) || result.skipped.some((s) => s.id === m.id)
     );
     if (allComplete) {
-      await bumpVersion(flintPath, step);
+      if (isVersionStepSealed(step)) {
+        await bumpVersion(flintPath, step);
+      } else {
+        const log = options.log || (() => {
+        });
+        log(`Version step ${step} is unsealed \u2014 migrations applied but version not advanced. Seal the version step when all planned migrations are implemented.`);
+      }
     }
   }
   return result;
 }
+async function runSingleMigration(flintPath, migrationId, options = {}) {
+  const result = {
+    applied: [],
+    skipped: [],
+    failed: [],
+    pending: []
+  };
+  const migration = migrations.find((m) => m.id === migrationId);
+  if (!migration) {
+    result.failed.push({
+      id: migrationId,
+      name: migrationId,
+      error: `No migration found with ID "${migrationId}"`
+    });
+    return result;
+  }
+  const alreadyDone = await hasMigration(flintPath, migration);
+  if (alreadyDone) {
+    await canonicalizeMigrationRecord(flintPath, migration);
+    result.skipped.push({ id: migration.id, name: migration.name });
+    return result;
+  }
+  const ctx = createMigrationContext(flintPath, options);
+  try {
+    const shouldRun = await migration.check(ctx);
+    if (!shouldRun) {
+      await recordMigration(flintPath, migration.id);
+      result.skipped.push({ id: migration.id, name: migration.name });
+      return result;
+    }
+    const runResult = await migration.run(ctx);
+    if (!runResult.success) {
+      result.failed.push({
+        id: migration.id,
+        name: migration.name,
+        error: "Migration run() returned success: false"
+      });
+      return result;
+    }
+    const verified = await migration.verify(ctx);
+    if (!verified) {
+      result.failed.push({
+        id: migration.id,
+        name: migration.name,
+        error: "Migration verification failed"
+      });
+      return result;
+    }
+    await recordMigration(flintPath, migration.id);
+    result.applied.push({
+      id: migration.id,
+      name: migration.name,
+      changes: runResult.changes,
+      warnings: runResult.warnings
+    });
+  } catch (err) {
+    result.failed.push({
+      id: migration.id,
+      name: migration.name,
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+  return result;
+}
 
 // ../../packages/flint/dist/index.js
 import { join as join12, resolve as resolve5, isAbsolute as isAbsolute2 } from "path";
@@ -2085,7 +2374,7 @@ import { rename as rename32 } from "fs/promises";
 import { basename as basename4, dirname as dirname5, join as join17 } from "path";
 import { exec as exec5 } from "child_process";
 import { promisify as promisify6 } from "util";
-import { readFile as readFile9, writeFile as writeFile10, readdir as readdir8 } from "fs/promises";
+import { readFile as readFile9, writeFile as writeFile10, readdir as readdir82 } from "fs/promises";
 import { join as join16 } from "path";
 import { stat as stat82, mkdir as mkdir12 } from "fs/promises";
 import { readdir as readdir9, readFile as readFile10, mkdir as mkdir13 } from "fs/promises";
@@ -2129,9 +2418,9 @@ async function createFlintStructure(options) {
     }
   }
   const folderName = formatFlintFolderName(name);
-  const flintPath = join10(parentDir, folderName);
+  const flintPath = join11(parentDir, folderName);
   try {
-    await stat8(flintPath);
+    await stat9(flintPath);
     throw new Error(`Folder already exists: ${flintPath}`);
   } catch (error) {
     if (error.code !== "ENOENT") {
@@ -2140,7 +2429,7 @@ async function createFlintStructure(options) {
   }
   await mkdir2(flintPath, { recursive: true });
   for (const dir of STANDARD_DIRECTORIES) {
-    await mkdir2(join10(flintPath, dir), { recursive: true });
+    await mkdir2(join11(flintPath, dir), { recursive: true });
   }
   const flintConfigDir = getFlintConfigDir(flintPath);
   await mkdir2(flintConfigDir, { recursive: true });
@@ -2255,7 +2544,7 @@ async function scanDirectory(dirPath, currentDepth, maxDepth, registeredPaths) {
       }
       return discovered;
     }
-    const entries = await readdir7(dirPath, { withFileTypes: true });
+    const entries = await readdir8(dirPath, { withFileTypes: true });
     for (const entry of entries) {
       if (entry.name.startsWith(".")) continue;
       if (entry.name === "node_modules") continue;
@@ -2436,10 +2725,10 @@ function validateManifest(manifest, manifestPath) {
   }
   const record = manifest;
   const name = typeof record.name === "string" ? record.name.trim() : "";
-  const display = typeof record.display === "string" ? record.display.trim() : "";
+  const title = typeof record.title === "string" ? record.title.trim() : "";
   const entry = typeof record.entry === "string" ? record.entry.trim() : "";
-  if (!name || !display || !entry) {
-    throw new Error(`plate.yaml is missing required fields (name, display, entry): ${manifestPath}`);
+  if (!name || !title || !entry) {
+    throw new Error(`plate.yaml is missing required fields (name, title, entry): ${manifestPath}`);
   }
   if (!isSlug(name)) {
     throw new Error(`Invalid plate name "${name}" in ${manifestPath}`);
@@ -2459,7 +2748,7 @@ function validateManifest(manifest, manifestPath) {
   }) : void 0;
   return {
     name,
-    display,
+    title,
     entry,
     version: typeof record.version === "string" ? record.version : void 0,
     description: typeof record.description === "string" ? record.description : void 0,
@@ -2600,8 +2889,7 @@ async function syncPlateRepos(flintPath, declarations) {
     const exists2 = await fileExists2(absolutePath);
     try {
       if (exists2) {
-        await updatePlateFromRepo(flintPath, name, decl.repo, decl.path);
-        results.push({ name, status: "updated" });
+        results.push({ name, status: "skipped" });
       } else {
         await clonePlateFromRepo(flintPath, name, decl.repo, decl.path);
         results.push({ name, status: "cloned" });
@@ -2629,7 +2917,7 @@ async function listPlates(flintPath) {
     }
     seenNames.add(normalized);
   }
-  return infos.sort((left, right) => left.manifest.display.localeCompare(right.manifest.display));
+  return infos.sort((left, right) => left.manifest.title.localeCompare(right.manifest.title));
 }
 async function getPlate(flintPath, plateName) {
   const normalized = normalizePlateName(plateName);
@@ -2638,12 +2926,12 @@ async function getPlate(flintPath, plateName) {
     (plate) => normalizePlateName(plate.declarationName) === normalized || normalizePlateName(plate.manifest.name) === normalized
   ) ?? null;
 }
-function renderPlateManifestYaml(slug, display, shard) {
+function renderPlateManifestYaml(slug, title, shard) {
   const manifest = {
     name: slug,
-    display,
+    title,
     version: "0.1.0",
-    description: `${display} Plate`,
+    description: `${title} Plate`,
     entry: "./dist/index.html",
     dev: "./src/index.tsx",
     api: ["GET /api/plates", "GET /api/artifacts"]
@@ -2846,6 +3134,13 @@ function spawnBufferedProcess(command, args, options) {
     });
   });
 }
+async function installPlateDeps(flintPath, plateName) {
+  const plate = await getPlate(flintPath, plateName);
+  if (!plate) {
+    throw new Error(`Plate not found: ${plateName}`);
+  }
+  return spawnBufferedProcess("pnpm", ["install"], { cwd: plate.path });
+}
 async function buildPlate(flintPath, plateName) {
   const plate = await getPlate(flintPath, plateName);
   if (!plate) {
@@ -3112,7 +3407,7 @@ function sanitizeLimit(limit) {
   if (!Number.isFinite(limit)) {
     return 100;
   }
-  return Math.max(1, Math.min(1e3, Math.trunc(limit)));
+  return Math.max(1, Math.min(1e4, Math.trunc(limit)));
 }
 function sanitizeOffset(offset) {
   if (!Number.isFinite(offset)) {
@@ -3415,6 +3710,11 @@ async function createProposalArtifact(flintPath, data) {
   const identity = await getIdentity(flintPath);
   const id = randomUUID3();
   const increment = ensureWikilink(typeof data.increment === "string" ? data.increment : void 0);
+  const relatedDocuments = asStringArray(data.relatedDocuments);
+  const alternativesConsidered = asStringArray(data.alternativesConsidered);
+  const tradeOffsAndRisks = asStringArray(data.tradeOffsAndRisks);
+  const notes = asStringArray(data.notes);
+  const logEntries = asStringArray(data.proposalLog);
   const frontmatter = {
     id,
     tags: ["#prop/proposal"],
@@ -3423,41 +3723,90 @@ async function createProposalArtifact(flintPath, data) {
   };
   if (increment) frontmatter.increment = increment;
   if (identity) frontmatter.authors = [`[[${identity.person}]]`];
-  const body = typeof data.context === "string" && data.context.trim() ? data.context.trim() : [
+  const proposalLog = [
+    ...logEntries,
+    `${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}: Artifact created via Flint Server artifact API.`
+  ];
+  const bodyLines = [
     "# Context & Motivation",
     "",
-    "Created via the Flint Server artifact API.",
+    typeof data.context === "string" && data.context.trim() ? data.context.trim() : "Created via the Flint Server artifact API.",
     "",
     "**Related Documents**",
     "",
+    ...relatedDocuments.length > 0 ? relatedDocuments.map((doc) => `- ${ensureWikilink(doc) ?? doc}`) : ["-"],
+    "",
     "# Current State",
     "",
+    typeof data.currentState === "string" && data.currentState.trim() ? data.currentState.trim() : "The current state will be researched and documented by the agent.",
+    "",
     "# Proposed Approach",
     "",
+    typeof data.proposedApproach === "string" && data.proposedApproach.trim() ? data.proposedApproach.trim() : "The proposed approach will be refined from the raw prompt and surrounding context.",
+    "",
     "# Alternatives Considered",
     "",
+    ...alternativesConsidered.length > 0 ? alternativesConsidered : ["Compare viable alternatives and explain why they were not selected."],
+    "",
     "# Trade-offs & Risks",
     "",
+    ...tradeOffsAndRisks.length > 0 ? tradeOffsAndRisks.map((item) => `- ${item}`) : ["- Document key trade-offs, risks, and mitigations before finalizing the recommendation."],
+    "",
     "# Recommendation",
     "",
+    typeof data.recommendation === "string" && data.recommendation.trim() ? data.recommendation.trim() : "A recommendation will be provided once the proposal is complete.",
+    "",
     "# Decision",
     "",
+    "",
     "# Proposal Log",
     "",
-    `- ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}: Artifact created via Flint Server artifact API.`,
+    ...proposalLog.map((entry) => `- ${entry}`),
     "",
     "# Notes",
+    "",
+    ...notes.length > 0 ? notes.map((note) => `- ${note}`) : ["-"],
     ""
-  ].join("\n");
+  ];
   const filePath = join82(flintPath, "Mesh", "Types", "Proposals", `(Proposal) ${number} ${title}.md`);
   await mkdir6(dirname22(filePath), { recursive: true });
-  await writeFile52(filePath, stringifyArtifact(frontmatter, body), "utf8");
+  await writeFile52(filePath, stringifyArtifact(frontmatter, bodyLines.join("\n")), "utf8");
   const created = await readArtifactAtPath(flintPath, filePath);
   if (!created) {
     throw new Error("Failed to create proposal artifact");
   }
   return created;
 }
+async function createStubArtifact(flintPath, data) {
+  const relativePath = typeof data.path === "string" ? data.path : "";
+  if (!relativePath) {
+    throw new Error('Stub artifact requires a "path" field');
+  }
+  const tags = Array.isArray(data.tags) ? data.tags : [];
+  const status = typeof data.status === "string" ? data.status : "stub";
+  const stubType = typeof data.type === "string" ? data.type : "Artifact";
+  const identity = await getIdentity(flintPath);
+  const frontmatter = {
+    id: randomUUID3(),
+    tags,
+    status
+  };
+  if (identity) {
+    frontmatter.authors = [`[[${identity.person}]]`];
+  }
+  const body = `# ${stubType} Stub
+
+This artifact is being created by an agent session. Content will replace this stub shortly.
+`;
+  const filePath = join82(flintPath, relativePath);
+  await mkdir6(dirname22(filePath), { recursive: true });
+  await writeFile52(filePath, stringifyArtifact(frontmatter, body), "utf8");
+  const created = await readArtifactAtPath(flintPath, filePath);
+  if (!created) {
+    throw new Error("Failed to create stub artifact");
+  }
+  return created;
+}
 async function createArtifactFromTemplate(flintPath, request) {
   switch (request.template) {
     case "tmp-proj-task-v0.1":
@@ -3470,6 +3819,8 @@ async function createArtifactFromTemplate(flintPath, request) {
       return createNoteArtifact(flintPath, "#note/concept", request.data);
     case "tmp-f-record-v0.1":
       return createNoteArtifact(flintPath, "#note/record", request.data);
+    case "stub":
+      return createStubArtifact(flintPath, request.data);
     default:
       throw new Error(`Unsupported template: ${request.template}`);
   }
@@ -4007,7 +4358,7 @@ function isDirectionalConnection(value) {
   return "from" in value && "to" in value;
 }
 function getConfigPath(root) {
-  return join11(root, TINDERBOX_CONFIG_FILENAME);
+  return join112(root, TINDERBOX_CONFIG_FILENAME);
 }
 function getTinderboxFlintMode(declaration) {
   if (declaration.mode) {
@@ -4145,7 +4496,7 @@ async function validateTinderboxToml(root, config) {
   if (!config.tinderbox.name.trim()) {
     throw new Error("Invalid tinderbox.toml: [tinderbox].name must be a non-empty string");
   }
-  if (await pathExists3(join11(root, "flint.toml"))) {
+  if (await pathExists3(join112(root, "flint.toml"))) {
     throw new Error("Invalid tinderbox root: the tinderbox root must not also be a Flint");
   }
   if (!config.flints.required.length) {
@@ -4250,8 +4601,8 @@ async function scanTinderboxFlints(root) {
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
     if (entry.name.startsWith(".")) continue;
-    const flintPath = join11(root, entry.name);
-    if (!await pathExists3(join11(flintPath, "flint.toml"))) {
+    const flintPath = join112(root, entry.name);
+    if (!await pathExists3(join112(flintPath, "flint.toml"))) {
       continue;
     }
     const config = await readFlintToml(flintPath);
@@ -4281,8 +4632,8 @@ async function reconcileTinderbox(root, config) {
       matched.push({ declaration, actual });
       continue;
     }
-    const expectedPath = join11(root, getTinderboxFolderName(declaration.name));
-    if (await pathExists3(join11(expectedPath, "flint.toml"))) {
+    const expectedPath = join112(root, getTinderboxFolderName(declaration.name));
+    if (await pathExists3(join112(expectedPath, "flint.toml"))) {
       const expectedConfig = await readFlintToml(expectedPath);
       const actualName = expectedConfig?.flint?.name;
       if (actualName && actualName !== declaration.name) {
@@ -4359,11 +4710,11 @@ var REQUIRED_FLINT_DIRS = [
 ];
 async function ensureFlintStructure(flintPath) {
   for (const dir of REQUIRED_FLINT_DIRS) {
-    await mkdir9(join11(flintPath, dir), { recursive: true });
+    await mkdir9(join112(flintPath, dir), { recursive: true });
   }
 }
 async function materializeGitFlint(root, declaration) {
-  const tempPath = join11(root, `.tinderbox-clone-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+  const tempPath = join112(root, `.tinderbox-clone-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
   try {
     await execFileAsync("git", ["clone", declaration.source, tempPath]);
     const config = await readFlintToml(tempPath);
@@ -4374,7 +4725,7 @@ async function materializeGitFlint(root, declaration) {
     if (actualName !== declaration.name) {
       throw new Error(`Cloned Flint name "${actualName}" does not match declared name "${declaration.name}"`);
     }
-    const destination = join11(root, getTinderboxFolderName(actualName));
+    const destination = join112(root, getTinderboxFolderName(actualName));
     if (await pathExists3(destination)) {
       throw new Error(`Destination already exists: ${destination}`);
     }
@@ -4529,6 +4880,7 @@ async function syncTinderbox(root) {
   const config = await readTinderboxToml(root);
   const initialReconciliation = await reconcileTinderbox(root, config);
   const cloned = [];
+  const moved = [];
   const referenced = [];
   const present = initialReconciliation.matched.map(({ declaration }) => declaration.name);
   const registryUpdated = [];
@@ -4536,6 +4888,13 @@ async function syncTinderbox(root) {
   const errors = [];
   for (const { declaration } of initialReconciliation.missing) {
     try {
+      const existingEntry = await findFlintByName(declaration.name);
+      if (existingEntry && await pathExists3(existingEntry.path)) {
+        const destination = join112(root, getTinderboxFolderName(declaration.name));
+        const moveResult = await moveFlint(existingEntry.path, destination);
+        moved.push({ name: declaration.name, from: moveResult.from, to: moveResult.to });
+        continue;
+      }
       await materializeGitFlint(root, declaration);
       cloned.push(declaration.name);
     } catch (error) {
@@ -4571,6 +4930,7 @@ async function syncTinderbox(root) {
   return {
     root,
     cloned,
+    moved,
     referenced,
     present,
     registryUpdated,
@@ -4728,13 +5088,13 @@ async function countFiles(path) {
   const entries = await readdir42(path, { withFileTypes: true });
   let count = 1;
   for (const entry of entries) {
-    count += await countFiles(join11(path, entry.name));
+    count += await countFiles(join112(path, entry.name));
   }
   return count;
 }
 async function resolveMoveSource(nameOrPath) {
   const directPath = resolve4(nameOrPath);
-  if (await pathExists3(join11(directPath, "flint.toml"))) {
+  if (await pathExists3(join112(directPath, "flint.toml"))) {
     const config = await readFlintToml(directPath);
     const name = config?.flint?.name;
     if (!name) {
@@ -4805,7 +5165,7 @@ async function moveFlint(nameOrPath, destination, options = {}) {
 async function removeTinderboxFlint(flint) {
   const entry = await findFlintByPath(flint.path);
   if (entry) {
-    const { unregisterFlint: unregisterFlint2 } = await import("./registry-YN5W7EY7-2W767O74.js");
+    const { unregisterFlint: unregisterFlint2 } = await import("./registry-YN5W7EY7-SZNXPBV5.js");
     await unregisterFlint2(entry.path);
   }
   await rm52(flint.path, { recursive: true, force: true });
@@ -6444,7 +6804,7 @@ async function buildShardEntries(flintPath) {
   if (!await exists(shardsDir)) return [];
   const entries = [];
   try {
-    const folders = await readdir8(shardsDir, { withFileTypes: true });
+    const folders = await readdir82(shardsDir, { withFileTypes: true });
     for (const folder of folders) {
       if (!folder.isDirectory() || folder.name.startsWith("(System)")) continue;
       const gitDir = join16(shardsDir, folder.name, ".git");
@@ -6876,9 +7236,9 @@ async function syncFlint(flintPath, progress) {
     }
   }
   const requiredMeshExports = config.sources?.meshexports || [];
-  const { getFlintRegistry: getFlintRegistry2 } = await import("./registry-YN5W7EY7-2W767O74.js");
+  const { getFlintRegistry: getFlintRegistry2 } = await import("./registry-YN5W7EY7-SZNXPBV5.js");
   const { readdir: readdir10, readFile: fsReadFile, rm: rm8, stat: fsStat, mkdir: fsMkdir, copyFile: fsCopyFile } = await import("fs/promises");
-  const { syncSourceMeshExportMetadata: syncSourceMeshExportMetadata2 } = await import("./metadata-SJT4H53O-EXBS6PS4.js");
+  const { syncSourceMeshExportMetadata: syncSourceMeshExportMetadata2 } = await import("./metadata-SJT4H53O-7W2752ZT.js");
   const requiredMeshExportSet = new Set(requiredMeshExports);
   const sourcesFlintDir = join17(flintPath, "Sources", "Flints");
   try {
@@ -6920,7 +7280,7 @@ async function syncFlint(flintPath, progress) {
   }
   if (requiredMeshExports.length > 0) {
     const registry = await getFlintRegistry2();
-    const { buildExportByName: buildExportByName2, scanExports: scanExports2 } = await import("./exports-E3262H6I-A4GXPTSR.js");
+    const { buildExportByName: buildExportByName2, scanExports: scanExports2 } = await import("./exports-FO5IMLM7-EN6H3N2A.js");
     for (const ref of requiredMeshExports) {
       const parts = ref.split("/");
       if (parts.length !== 2) {
@@ -7064,7 +7424,7 @@ async function syncFlint(flintPath, progress) {
       error: `Failed to sync source repo metadata: ${err instanceof Error ? err.message : String(err)}`
     });
   }
-  const { getPlateDeclarationsFromConfig } = await import("./mesh-config-BAIYF4KD-QNNQOBSL.js");
+  const { getPlateDeclarationsFromConfig } = await import("./mesh-config-BAIYF4KD-W2RGZQ2V.js");
   const plateDeclarations = getPlateDeclarationsFromConfig(config);
   const hasRepoPlates = Object.values(plateDeclarations).some((d) => d.repo);
   if (hasRepoPlates) {
@@ -7334,7 +7694,7 @@ function getSessionInterface(flintPath, sessionId, key) {
 }
 function getCurrentRun(session) {
   if (session.runs.length === 0) return null;
-  return session.runs[session.runs.length - 1];
+  return session.runs[session.runs.length - 1] ?? null;
 }
 function addRun(flintPath, sessionId, options) {
   const session = readSession(flintPath, sessionId);
@@ -7422,7 +7782,7 @@ function resolveSession(flintPath, partialId) {
   if (exact) return exact;
   const sessions = listSessions(flintPath);
   const matches = sessions.filter((s) => s.id.startsWith(partialId));
-  if (matches.length === 1) return matches[0];
+  if (matches.length === 1) return matches[0] ?? null;
   return null;
 }
 var VALID_STATUSES = ["queued", "in-progress", "blocked", "finished", "failed"];
@@ -7939,8 +8299,12 @@ var LiveSessionManager = class {
 
 export {
   compareVersions,
+  isVersionStepSealed,
+  getVersionSteps,
+  getMigrationsForVersion,
   checkMigrations,
   runMigrations,
+  runSingleMigration,
   STANDARD_DIRECTORIES,
   createFlint,
   findFlintRoot,
@@ -7970,6 +8334,7 @@ export {
   listPlates,
   getPlate,
   createPlate,
+  installPlateDeps,
   buildPlate,
   runPlateTool,
   listPlateTools,