@hasna/todos 0.11.70 → 0.11.71

package/dist/cli/commands/plan-template-commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan-template-commands.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/plan-template-commands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAczC,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,OAAO,QA6e5D"}
+{"version":3,"file":"plan-template-commands.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/plan-template-commands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8BzC,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,OAAO,QAqe5D"}

package/dist/cli/index.js

@@ -3282,6 +3282,11 @@ var init_migrations = __esm(() => {
   CREATE INDEX IF NOT EXISTS idx_storage_tombstones_object ON storage_tombstones(object_type, object_id);
   CREATE INDEX IF NOT EXISTS idx_storage_tombstones_updated ON storage_tombstones(updated_at);
   INSERT OR IGNORE INTO _migrations (id) VALUES (63);
+  `,
+    `
+  ALTER TABLE plans ADD COLUMN slug TEXT;
+  CREATE INDEX IF NOT EXISTS idx_plans_slug ON plans(slug);
+  INSERT OR IGNORE INTO _migrations (id) VALUES (64);
   `
   ];
 });
@@ -3305,6 +3310,29 @@ function runMigrations(db) {
   }
   ensureSchema(db);
 }
+function planSlugBase(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "plan";
+}
+function backfillPlanSlugs(db) {
+  try {
+    const rows = db.query("SELECT id, project_id, name, slug FROM plans ORDER BY created_at ASC, id ASC").all();
+    const used = new Set;
+    for (const row of rows) {
+      const scope = row.project_id ?? "__global__";
+      const base = planSlugBase(row.slug || row.name);
+      let candidate = base;
+      let suffix = 2;
+      while (used.has(`${scope}:${candidate}`)) {
+        candidate = `${base}-${suffix}`;
+        suffix += 1;
+      }
+      used.add(`${scope}:${candidate}`);
+      if (row.slug !== candidate) {
+        db.run("UPDATE plans SET slug = ? WHERE id = ?", [candidate, row.id]);
+      }
+    }
+  } catch {}
+}
 function ensureSchema(db) {
   const ensureColumn = (table, column, type) => {
     try {
@@ -3354,7 +3382,8 @@ function ensureSchema(db) {
     )`);
   ensureTable("plans", `
     CREATE TABLE plans (
-      id TEXT PRIMARY KEY, project_id TEXT REFERENCES projects(id) ON DELETE CASCADE,
+      id TEXT PRIMARY KEY, slug TEXT,
+      project_id TEXT REFERENCES projects(id) ON DELETE CASCADE,
       task_list_id TEXT, agent_id TEXT,
       name TEXT NOT NULL, description TEXT,
       status TEXT NOT NULL DEFAULT 'active' CHECK(status IN ('active', 'completed', 'archived')),
@@ -3869,8 +3898,10 @@ function ensureSchema(db) {
   ensureColumn("agents", "org_id", "TEXT");
   ensureColumn("agents", "capabilities", "TEXT DEFAULT '[]'");
   ensureColumn("projects", "org_id", "TEXT");
+  ensureColumn("plans", "slug", "TEXT");
   ensureColumn("plans", "task_list_id", "TEXT");
   ensureColumn("plans", "agent_id", "TEXT");
+  backfillPlanSlugs(db);
   ensureColumn("task_templates", "variables", "TEXT DEFAULT '[]'");
   ensureColumn("task_templates", "version", "INTEGER NOT NULL DEFAULT 1");
   ensureColumn("template_tasks", "condition", "TEXT");
@@ -3985,6 +4016,8 @@ function ensureSchema(db) {
   ensureIndex("CREATE INDEX IF NOT EXISTS idx_tags_name ON tags(name)");
   ensureIndex("CREATE INDEX IF NOT EXISTS idx_plans_project ON plans(project_id)");
   ensureIndex("CREATE INDEX IF NOT EXISTS idx_plans_status ON plans(status)");
+  ensureIndex("CREATE INDEX IF NOT EXISTS idx_plans_slug ON plans(slug)");
+  ensureIndex("CREATE UNIQUE INDEX IF NOT EXISTS idx_plans_scope_slug ON plans(COALESCE(project_id, ''), slug) WHERE slug IS NOT NULL");
   ensureIndex("CREATE INDEX IF NOT EXISTS idx_plans_task_list ON plans(task_list_id)");
   ensureIndex("CREATE INDEX IF NOT EXISTS idx_plans_agent ON plans(agent_id)");
   ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_history_task ON task_history(task_id)");
@@ -4838,6 +4871,9 @@ function clearExpiredLocks(db) {
   const cutoff = lockExpiryCutoff();
   db.run("UPDATE tasks SET locked_by = NULL, locked_at = NULL WHERE locked_at IS NOT NULL AND locked_at < ?", [cutoff]);
 }
+function slugifyRef(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
 function resolvePartialId(db, table, partialId) {
   if (!ALLOWED_TABLES.has(table)) {
     throw new Error(`Invalid table name: ${table}`);
@@ -4864,6 +4900,16 @@ function resolvePartialId(db, table, partialId) {
     if (slugRow)
       return slugRow.id;
   }
+  if (table === "plans") {
+    const slug = slugifyRef(partialId);
+    if (slug) {
+      const slugRows = db.query("SELECT id FROM plans WHERE slug = ?").all(slug);
+      if (slugRows.length === 1)
+        return slugRows[0].id;
+      if (slugRows.length > 1)
+        return null;
+    }
+  }
   if (table === "projects") {
     const nameRow = db.query("SELECT id FROM projects WHERE lower(name) = ?").get(partialId.toLowerCase());
     if (nameRow)
@@ -10333,15 +10379,76 @@ var init_task_relations = __esm(() => {
 });
 
 // src/db/plans.ts
+function planSlugBase2(value) {
+  return slugify(value) || "plan";
+}
+function normalizePlanSlug(value) {
+  const slug = slugify(value);
+  if (!slug)
+    throw new Error("Invalid plan slug");
+  return slug;
+}
+function plansBySlug(slug, db, projectId) {
+  if (projectId !== undefined) {
+    if (projectId === null) {
+      return db.query("SELECT * FROM plans WHERE slug = ? AND project_id IS NULL ORDER BY created_at ASC, id ASC").all(slug);
+    }
+    return db.query("SELECT * FROM plans WHERE slug = ? AND project_id = ? ORDER BY created_at ASC, id ASC").all(slug, projectId);
+  }
+  return db.query("SELECT * FROM plans WHERE slug = ? ORDER BY created_at ASC, id ASC").all(slug);
+}
+function planSlugExists(slug, projectId, db, excludeId) {
+  const rows = plansBySlug(slug, db, projectId);
+  return rows.some((plan) => plan.id !== excludeId);
+}
+function nextPlanSlug(base, projectId, db, excludeId) {
+  let candidate = base;
+  let suffix = 2;
+  while (planSlugExists(candidate, projectId, db, excludeId)) {
+    candidate = `${base}-${suffix}`;
+    suffix += 1;
+  }
+  return candidate;
+}
+function resolveCreateSlug(input, projectId, db) {
+  if (input.slug !== undefined) {
+    const slug = normalizePlanSlug(input.slug);
+    if (planSlugExists(slug, projectId, db)) {
+      throw new Error(`Plan slug already exists in this scope: ${slug}`);
+    }
+    return slug;
+  }
+  return nextPlanSlug(planSlugBase2(input.name), projectId, db);
+}
+function resolvePlanRefDetailed(ref, db, projectId) {
+  const d = db || getDatabase();
+  const byId = d.query("SELECT * FROM plans WHERE id = ? OR id LIKE ? ORDER BY id").all(ref, `${ref}%`);
+  if (byId.length === 1)
+    return { id: byId[0].id, reason: "id", matches: byId };
+  if (byId.length > 1)
+    return { id: null, reason: "ambiguous", matches: byId };
+  const slug = slugify(ref);
+  if (!slug)
+    return { id: null, reason: "not_found", matches: [] };
+  const bySlug = plansBySlug(slug, d, projectId);
+  if (bySlug.length === 1)
+    return { id: bySlug[0].id, reason: "slug", matches: bySlug };
+  if (bySlug.length > 1)
+    return { id: null, reason: "ambiguous", matches: bySlug };
+  return { id: null, reason: "not_found", matches: [] };
+}
 function createPlan(input, db) {
   const d = db || getDatabase();
   const id = uuid();
   const timestamp = now();
+  const projectId = input.project_id || null;
+  const slug = resolveCreateSlug(input, projectId, d);
   const machineId = currentStorageMachineId(d);
-  d.run(`INSERT INTO plans (id, project_id, task_list_id, agent_id, name, description, status, created_at, updated_at, machine_id)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+  d.run(`INSERT INTO plans (id, slug, project_id, task_list_id, agent_id, name, description, status, created_at, updated_at, machine_id)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
     id,
-    input.project_id || null,
+    slug,
+    projectId,
     input.task_list_id || null,
     input.agent_id || null,
     input.name,
@@ -10376,6 +10483,14 @@ function updatePlan(id, input, db) {
     sets.push("name = ?");
     params.push(input.name);
   }
+  if (input.slug !== undefined) {
+    const slug = normalizePlanSlug(input.slug);
+    if (planSlugExists(slug, plan.project_id, d, id)) {
+      throw new Error(`Plan slug already exists in this scope: ${slug}`);
+    }
+    sets.push("slug = ?");
+    params.push(slug);
+  }
   if (input.description !== undefined) {
     sets.push("description = ?");
     params.push(input.description);
@@ -10420,6 +10535,7 @@ var init_plans = __esm(() => {
   init_event_emission_safety();
   init_event_hooks();
   init_database();
+  init_projects();
   init_storage_tombstones();
 });
 
@@ -13718,6 +13834,9 @@ function projectSlugMatches(project, ref) {
   const normalized = slugify(ref);
   return Boolean(normalized) && (project.task_list_id === normalized || slugify(project.name) === normalized);
 }
+function planArtifactSlug(plan) {
+  return slugify(plan.slug || plan.name) || "plan";
+}
 function resolvePlanArtifactProject(input) {
   const db = input.db || getDatabase();
   const ref = input.project_id || input.project_ref;
@@ -13743,11 +13862,24 @@ function resolvePlanArtifactPaths(input) {
   const projectRoot = resolve10(project.path);
   const directory = join7(projectRoot, ".hasna", "todos", "plans", projectId);
   const planId = input.plan_id ? assertSafePathSegment(input.plan_id, "plan id") : null;
+  const planSlug = input.plan_slug ? assertSafePathSegment(slugify(input.plan_slug), "plan slug") : null;
+  const fileName = planId ? planSlug ? `${planSlug}--${planId.slice(0, 8)}.md` : `${planId}.md` : null;
   return {
     project_id: project.id,
     project_root: projectRoot,
     directory,
-    file_path: planId ? join7(directory, `${planId}.md`) : directory
+    file_path: fileName ? join7(directory, fileName) : directory
+  };
+}
+function resolvePlanArtifactCandidatePaths(plan, db) {
+  return {
+    primary: resolvePlanArtifactPaths({
+      project_id: plan.project_id,
+      plan_id: plan.id,
+      plan_slug: planArtifactSlug(plan),
+      db
+    }),
+    legacy: resolvePlanArtifactPaths({ project_id: plan.project_id, plan_id: plan.id, db })
   };
 }
 function buildPlanArtifactSnapshot(plan, tasks = [], artifactUpdatedAt = new Date().toISOString()) {
@@ -13764,6 +13896,7 @@ function buildPlanArtifactSnapshot(plan, tasks = [], artifactUpdatedAt = new Dat
     metadata: {
       schema: PLAN_MARKDOWN_SCHEMA,
       plan_id: plan.id,
+      plan_slug: plan.slug ?? null,
       project_id: plan.project_id,
       task_list_id: plan.task_list_id ?? null,
       agent_id: plan.agent_id ?? null,
@@ -13803,6 +13936,7 @@ function renderPlanArtifactMarkdown(snapshot) {
     "---",
     `schema: ${frontmatterScalar(metadata.schema)}`,
     `plan_id: ${frontmatterScalar(metadata.plan_id)}`,
+    `plan_slug: ${frontmatterScalar(metadata.plan_slug)}`,
     `project_id: ${frontmatterScalar(metadata.project_id)}`,
     `task_list_id: ${frontmatterScalar(metadata.task_list_id)}`,
     `agent_id: ${frontmatterScalar(metadata.agent_id)}`,
@@ -13848,6 +13982,7 @@ function parsePlanArtifactMarkdown(markdown) {
     metadata: {
       schema: PLAN_MARKDOWN_SCHEMA,
       plan_id: rawMetadata.plan_id,
+      plan_slug: rawMetadata.plan_slug ?? null,
       project_id: rawMetadata.project_id,
       task_list_id: rawMetadata.task_list_id ?? null,
       agent_id: rawMetadata.agent_id ?? null,
@@ -13888,7 +14023,7 @@ function writePlanArtifact(plan, db) {
     return null;
   const d = db || getDatabase();
   const tasks = listTasks({ plan_id: plan.id, include_archived: true }, d);
-  const paths = resolvePlanArtifactPaths({ project_id: plan.project_id, plan_id: plan.id, db: d });
+  const paths = resolvePlanArtifactCandidatePaths(plan, d).primary;
   const snapshot = buildPlanArtifactSnapshot(plan, tasks);
   mkdirSync5(paths.directory, { recursive: true });
   writeFileSync3(paths.file_path, renderPlanArtifactMarkdown(snapshot), "utf8");
@@ -13898,12 +14033,13 @@ function readPlanArtifact(plan, db) {
   if (!plan.project_id)
     return null;
   const d = db || getDatabase();
-  const paths = resolvePlanArtifactPaths({ project_id: plan.project_id, plan_id: plan.id, db: d });
-  if (!existsSync8(paths.file_path))
+  const paths = resolvePlanArtifactCandidatePaths(plan, d);
+  const path = existsSync8(paths.primary.file_path) ? paths.primary.file_path : existsSync8(paths.legacy.file_path) ? paths.legacy.file_path : null;
+  if (!path)
     return null;
-  const markdown = readFileSync4(paths.file_path, "utf8");
+  const markdown = readFileSync4(path, "utf8");
   return {
-    path: paths.file_path,
+    path,
     markdown,
     ...parsePlanArtifactMarkdown(markdown)
   };
@@ -13912,10 +14048,11 @@ function inspectPlanArtifact(plan, db) {
   if (!plan.project_id)
     return null;
   const d = db || getDatabase();
-  const paths = resolvePlanArtifactPaths({ project_id: plan.project_id, plan_id: plan.id, db: d });
-  if (!existsSync8(paths.file_path)) {
+  const paths = resolvePlanArtifactCandidatePaths(plan, d);
+  const path = existsSync8(paths.primary.file_path) ? paths.primary.file_path : existsSync8(paths.legacy.file_path) ? paths.legacy.file_path : null;
+  if (!path) {
     return {
-      path: paths.file_path,
+      path: paths.primary.file_path,
       exists: false,
       parse_error: null,
       metadata: null,
@@ -13924,9 +14061,9 @@ function inspectPlanArtifact(plan, db) {
     };
   }
   try {
-    const artifact = parsePlanArtifactMarkdown(readFileSync4(paths.file_path, "utf8"));
+    const artifact = parsePlanArtifactMarkdown(readFileSync4(path, "utf8"));
     return {
-      path: paths.file_path,
+      path,
       exists: true,
       parse_error: null,
       metadata: artifact.metadata,
@@ -13935,7 +14072,7 @@ function inspectPlanArtifact(plan, db) {
     };
   } catch (error) {
     return {
-      path: paths.file_path,
+      path,
       exists: true,
       parse_error: error instanceof Error ? error.message : String(error),
       metadata: null,
@@ -13947,6 +14084,9 @@ function inspectPlanArtifact(plan, db) {
 function comparePlanArtifact(plan, artifact, tasks) {
   const conflicts = [];
   compare("plan_id", plan.id, artifact.metadata.plan_id, conflicts);
+  if (artifact.metadata.plan_slug !== null) {
+    compare("plan_slug", plan.slug ?? null, artifact.metadata.plan_slug, conflicts);
+  }
   compare("project_id", plan.project_id ?? null, artifact.metadata.project_id, conflicts);
   compare("name", plan.name, artifact.metadata.name, conflicts);
   compare("status", plan.status, artifact.metadata.status, conflicts);
@@ -14316,22 +14456,44 @@ __export(exports_plan_template_commands, {
   registerPlanTemplateCommands: () => registerPlanTemplateCommands
 });
 import chalk3 from "chalk";
+function resolvePlanCliRef(ref, projectId) {
+  const db = getDatabase();
+  const resolved = resolvePlanRefDetailed(ref, db, projectId);
+  if (resolved.id)
+    return resolved.id;
+  if (resolved.reason === "ambiguous") {
+    console.error(chalk3.red(`Ambiguous plan reference: ${ref}`));
+    if (resolved.matches.length > 0) {
+      console.error(chalk3.dim(`Matches: ${resolved.matches.map((plan) => `${plan.slug ?? plan.name} (${plan.id.slice(0, 8)})`).join(", ")}`));
+    }
+  } else {
+    console.error(chalk3.red(`Could not resolve plan ID or slug: ${ref}`));
+  }
+  process.exit(1);
+}
 function registerPlanTemplateCommands(program2) {
-  program2.command("plans").description("List and manage plans").option("--add <name>", "Create a plan").option("-d, --description <text>", "Plan description (with --add)").option("--show <id>", "Show plan details with its tasks").option("--artifact <id>", "Show local Markdown artifact diagnostics for a plan").option("--write-artifacts", "Write local Markdown artifacts for all project-scoped plans in scope").option("--delete <id>", "Delete a plan").option("--complete <id>", "Mark a plan as completed").action((opts) => {
+  program2.command("plans").description("List and manage plans").option("--add <name>", "Create a plan").option("--slug <slug>", "Readable plan slug (with --add)").option("-d, --description <text>", "Plan description (with --add)").option("--show <id-or-slug>", "Show plan details with its tasks").option("--artifact <id-or-slug>", "Show local Markdown artifact diagnostics for a plan").option("--write-artifacts", "Write local Markdown artifacts for all project-scoped plans in scope").option("--delete <id>", "Delete a plan").option("--complete <id>", "Mark a plan as completed").action((opts) => {
     const globalOpts = program2.opts();
     const projectId = autoProject(globalOpts);
     if (opts.add) {
-      const plan = createPlan({
-        name: opts.add,
-        description: opts.description,
-        project_id: projectId
-      });
+      let plan;
+      try {
+        plan = createPlan({
+          name: opts.add,
+          slug: opts.slug,
+          description: opts.description,
+          project_id: projectId
+        });
+      } catch (error) {
+        handleError(error);
+      }
       const artifact = writePlanArtifact(plan);
       if (globalOpts.json) {
         output(plan, true);
       } else {
         console.log(chalk3.green("Plan created:"));
         console.log(`${chalk3.dim(plan.id.slice(0, 8))} ${chalk3.bold(plan.name)} ${chalk3.cyan(`[${plan.status}]`)}`);
+        console.log(`${chalk3.dim("Slug:")} ${plan.slug}`);
         if (artifact)
           console.log(`${chalk3.dim("Artifact:")} ${artifact.path}`);
       }
@@ -14339,11 +14501,7 @@ function registerPlanTemplateCommands(program2) {
     }
     if (opts.artifact) {
       const db = getDatabase();
-      const resolvedId = resolvePartialId(db, "plans", opts.artifact);
-      if (!resolvedId) {
-        console.error(chalk3.red(`Could not resolve plan ID: ${opts.artifact}`));
-        process.exit(1);
-      }
+      const resolvedId = resolvePlanCliRef(opts.artifact, projectId);
       const plan = getPlan(resolvedId);
       if (!plan) {
         console.error(chalk3.red(`Plan not found: ${opts.artifact}`));
@@ -14396,11 +14554,7 @@ function registerPlanTemplateCommands(program2) {
     }
     if (opts.show) {
       const db = getDatabase();
-      const resolvedId = resolvePartialId(db, "plans", opts.show);
-      if (!resolvedId) {
-        console.error(chalk3.red(`Could not resolve plan ID: ${opts.show}`));
-        process.exit(1);
-      }
+      const resolvedId = resolvePlanCliRef(opts.show, projectId);
       const plan = getPlan(resolvedId);
       if (!plan) {
         console.error(chalk3.red(`Plan not found: ${opts.show}`));
@@ -14425,6 +14579,8 @@ function registerPlanTemplateCommands(program2) {
       console.log(chalk3.bold(`Plan Details:
 `));
       console.log(`  ${chalk3.dim("ID:")}       ${plan.id}`);
+      if (plan.slug)
+        console.log(`  ${chalk3.dim("Slug:")}     ${plan.slug}`);
       console.log(`  ${chalk3.dim("Name:")}     ${plan.name}`);
       console.log(`  ${chalk3.dim("Status:")}   ${chalk3.cyan(plan.status)}`);
       if (plan.description)
@@ -14447,12 +14603,7 @@ function registerPlanTemplateCommands(program2) {
       return;
     }
     if (opts.delete) {
-      const db = getDatabase();
-      const resolvedId = resolvePartialId(db, "plans", opts.delete);
-      if (!resolvedId) {
-        console.error(chalk3.red(`Could not resolve plan ID: ${opts.delete}`));
-        process.exit(1);
-      }
+      const resolvedId = resolvePlanCliRef(opts.delete, projectId);
       const deleted = deletePlan(resolvedId);
       if (globalOpts.json) {
         output({ deleted }, true);
@@ -14465,12 +14616,7 @@ function registerPlanTemplateCommands(program2) {
       return;
     }
     if (opts.complete) {
-      const db = getDatabase();
-      const resolvedId = resolvePartialId(db, "plans", opts.complete);
-      if (!resolvedId) {
-        console.error(chalk3.red(`Could not resolve plan ID: ${opts.complete}`));
-        process.exit(1);
-      }
+      const resolvedId = resolvePlanCliRef(opts.complete, projectId);
       try {
         const plan = updatePlan(resolvedId, { status: "completed" });
         const artifact = writePlanArtifact(plan);
@@ -14500,7 +14646,8 @@ function registerPlanTemplateCommands(program2) {
 `));
     for (const p of plans) {
       const desc = p.description ? chalk3.dim(` - ${p.description}`) : "";
-      console.log(`${chalk3.dim(p.id.slice(0, 8))} ${chalk3.bold(p.name)} ${chalk3.cyan(`[${p.status}]`)}${desc}`);
+      const slug = p.slug ? chalk3.dim(` ${p.slug}`) : "";
+      console.log(`${chalk3.dim(p.id.slice(0, 8))}${slug} ${chalk3.bold(p.name)} ${chalk3.cyan(`[${p.status}]`)}${desc}`);
     }
   });
   program2.command("templates").description("List and manage task templates").option("--add <name>", "Create a template").option("--title <pattern>", "Title pattern (with --add)").option("-d, --description <text>", "Default description").option("-p, --priority <level>", "Default priority").option("-t, --tags <tags>", "Default tags (comma-separated)").option("--delete <id>", "Delete a template").option("--update <id>", "Update a template").option("--use <id>", "Create a task from a template").option("--var <vars...>", "Variable substitutions: key=value (e.g. --var feature=login)").action(async (opts) => {
@@ -22074,6 +22221,36 @@ function prepareValue(column, value) {
     return JSON.stringify(value ?? (column === "tags" || column === "files_changed" ? [] : {}));
   return value === undefined ? null : value;
 }
+function slugifyPlanValue(value) {
+  return typeof value === "string" ? value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") : "";
+}
+function planSlugBase3(plan) {
+  return slugifyPlanValue(plan.slug) || slugifyPlanValue(plan.name) || "plan";
+}
+function planSlugScope(projectId) {
+  return typeof projectId === "string" && projectId ? projectId : "__global__";
+}
+function planSlugKey(projectId, slug) {
+  return `${planSlugScope(projectId)}:${slug}`;
+}
+function normalizeBridgePlanSlugs(plans, db) {
+  const existingRows = db.query("SELECT id, project_id, slug FROM plans WHERE slug IS NOT NULL").all();
+  const existingIds = new Set(existingRows.map((row) => row.id));
+  const used = new Set(existingRows.filter((row) => row.slug).map((row) => planSlugKey(row.project_id, row.slug)));
+  return plans.map((plan) => {
+    if (existingIds.has(plan.id))
+      return plan;
+    const base = planSlugBase3(plan);
+    let candidate = base;
+    let suffix = 2;
+    while (used.has(planSlugKey(plan.project_id, candidate))) {
+      candidate = `${base}-${suffix}`;
+      suffix += 1;
+    }
+    used.add(planSlugKey(plan.project_id, candidate));
+    return { ...plan, slug: candidate };
+  });
+}
 function insertRecord(db, tableKey, row) {
   const table = tableByKey[tableKey];
   const columns = insertColumns[tableKey];
@@ -22210,6 +22387,7 @@ function importLocalBridgeBundle(bundle, options = {}, db) {
   const conflictStrategy = options.conflictStrategy ?? "skip";
   const data = {
     ...bundle.data,
+    plans: normalizeBridgePlanSlugs(bundle.data.plans, d),
     tasks: sortedTasks(bundle.data.tasks),
     saved_views: bundle.data.saved_views ?? [],
     task_boards: bundle.data.task_boards ?? [],
@@ -22294,7 +22472,7 @@ var init_local_bridge = __esm(() => {
   insertColumns = {
     projects: ["id", "name", "path", "description", "task_list_id", "task_prefix", "task_counter", "created_at", "updated_at", "machine_id", "synced_at"],
     task_lists: ["id", "project_id", "slug", "name", "description", "metadata", "created_at", "updated_at", "machine_id", "synced_at"],
-    plans: ["id", "project_id", "task_list_id", "agent_id", "name", "description", "status", "created_at", "updated_at", "machine_id", "synced_at"],
+    plans: ["id", "slug", "project_id", "task_list_id", "agent_id", "name", "description", "status", "created_at", "updated_at", "machine_id", "synced_at"],
     tasks: [
       "id",
       "short_id",
@@ -28389,6 +28567,7 @@ async function handleCreatePlan(req, _ctx, json2) {
       return json2({ error: "Missing 'name'" }, 400);
     const plan = createPlan({
       name: body.name,
+      slug: body.slug,
       description: body.description,
       project_id: body.project_id,
       task_list_id: body.task_list_id,
@@ -37738,6 +37917,7 @@ Tasks:` : null,
   if (shouldRegisterTool("create_plan")) {
     server.tool("create_plan", "Create a new plan (sprint/milestone).", {
       name: exports_external2.string().describe("Plan name"),
+      slug: exports_external2.string().optional().describe("Readable plan slug"),
       project_id: exports_external2.string().optional().describe("Project ID"),
       description: exports_external2.string().optional(),
       start_date: exports_external2.string().optional().describe("ISO date"),
@@ -44898,6 +45078,7 @@ function createAgentProjectDemoBundle() {
   });
   data.plans.push({
     id: ids.plan,
+    slug: "ship-local-demo-workflow",
     project_id: ids.project,
     task_list_id: ids.list,
     agent_id: "demo-agent",
@@ -66291,9 +66472,17 @@ async function updateProject2(id, input, store) {
 }
 async function createPlan2(input, store, context) {
   const timestamp3 = new Date().toISOString();
+  const projectId = input.project_id ?? context?.projectId ?? null;
+  const slug = await resolvePostgresPlanSlug({
+    name: input.name,
+    slug: input.slug,
+    projectId,
+    store
+  });
   return store.upsert("plans", {
     id: randomUUID3(),
-    project_id: input.project_id ?? context?.projectId ?? null,
+    slug,
+    project_id: projectId,
     task_list_id: input.task_list_id ?? context?.taskListId ?? null,
     agent_id: input.agent_id ?? context?.agentId ?? null,
     name: input.name,
@@ -66307,7 +66496,17 @@ async function createPlan2(input, store, context) {
 }
 async function updatePlan2(id, input, store) {
   const plan = await requireRecord("plans", id, store);
-  return store.upsert("plans", { ...plan, ...definedPatch(input), updated_at: new Date().toISOString() });
+  const patch = definedPatch(input);
+  if (input.slug !== undefined) {
+    patch.slug = await resolvePostgresPlanSlug({
+      name: plan.name,
+      slug: input.slug,
+      projectId: plan.project_id,
+      store,
+      excludeId: id
+    });
+  }
+  return store.upsert("plans", { ...plan, ...patch, updated_at: new Date().toISOString() });
 }
 async function registerAgent2(input, store, context) {
   const existing = (await store.list("agents")).find((agent2) => agent2.name === input.name && agent2.status !== "archived");
@@ -66560,8 +66759,38 @@ function matchesOne(value, expected) {
 function priorityRank2(priority) {
   return { critical: 0, high: 1, medium: 2, low: 3 }[priority];
 }
+function slugifyRaw(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
 function slugify2(value) {
-  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "todos";
+  return slugifyRaw(value) || "todos";
+}
+function normalizePlanSlug2(value) {
+  const slug = slugifyRaw(value);
+  if (!slug)
+    throw new Error("Invalid plan slug");
+  return slug;
+}
+function planSlugBase4(value) {
+  return slugifyRaw(value) || "plan";
+}
+async function resolvePostgresPlanSlug(options) {
+  const plans = await options.store.list("plans");
+  const used = new Set(plans.filter((plan) => plan.project_id === options.projectId && plan.id !== options.excludeId && plan.slug).map((plan) => plan.slug));
+  if (options.slug !== undefined) {
+    const slug = normalizePlanSlug2(options.slug);
+    if (used.has(slug))
+      throw new Error(`Plan slug already exists in this scope: ${slug}`);
+    return slug;
+  }
+  const base = planSlugBase4(options.name);
+  let candidate = base;
+  let suffix = 2;
+  while (used.has(candidate)) {
+    candidate = `${base}-${suffix}`;
+    suffix += 1;
+  }
+  return candidate;
 }
 function definedPatch(value) {
   return Object.fromEntries(Object.entries(value).filter(([, entry2]) => entry2 !== undefined));