@shipbench/core 0.1.0

package/dist/index.js

@@ -0,0 +1,1763 @@
+import {
+  byCreatedDesc,
+  byUpdatedDesc,
+  layoutAfterMove,
+  layoutWithoutTask,
+  orderedTasksForColumn
+} from "./chunk-7T2E4KSJ.js";
+
+// src/adapters/fs.ts
+import { mkdir, readdir, readFile, unlink, writeFile } from "fs/promises";
+import { dirname, join } from "path";
+var FsAdapter = class {
+  constructor(rootDir) {
+    this.rootDir = rootDir;
+  }
+  rootDir;
+  resolve(path) {
+    return join(this.rootDir, path);
+  }
+  async readFile(path) {
+    return readFile(this.resolve(path), "utf-8");
+  }
+  async readFileIfExists(path) {
+    try {
+      return await this.readFile(path);
+    } catch (error) {
+      if (error.code === "ENOENT") return null;
+      throw error;
+    }
+  }
+  async writeFile(path, content) {
+    const fullPath = this.resolve(path);
+    await mkdir(dirname(fullPath), { recursive: true });
+    await writeFile(fullPath, content, "utf-8");
+  }
+  async deleteFile(path) {
+    await unlink(this.resolve(path));
+  }
+  async listFiles(directory) {
+    try {
+      return await readdir(this.resolve(directory));
+    } catch {
+      return [];
+    }
+  }
+  async readFiles(paths) {
+    const results = /* @__PURE__ */ new Map();
+    for (const path of paths) {
+      const content = await this.readFile(path);
+      results.set(path, content);
+    }
+    return results;
+  }
+  async writeFiles(files) {
+    for (const [path, content] of files) {
+      await this.writeFile(path, content);
+    }
+  }
+};
+
+// src/adapters/github.ts
+var GitHubApiError = class extends Error {
+  status;
+  statusText;
+  operation;
+  path;
+  constructor(options) {
+    const { status, statusText, operation, path, body } = options;
+    super(
+      `GitHubAdapter.${operation}: ${status} ${statusText} for "${path}"${body ? ` \u2014 ${body}` : ""}`
+    );
+    this.name = "GitHubApiError";
+    this.status = status;
+    this.statusText = statusText;
+    this.operation = operation;
+    this.path = path;
+  }
+};
+var API_BASE = "https://api.github.com";
+function utf8ToBase64(s) {
+  const bytes = new TextEncoder().encode(s);
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin);
+}
+function base64ToUtf8(s) {
+  const bin = atob(s.replace(/\s+/g, ""));
+  const bytes = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+  return new TextDecoder().decode(bytes);
+}
+function encodePath(path) {
+  return path.split("/").map(encodeURIComponent).join("/");
+}
+var GitHubAdapter = class {
+  owner;
+  repo;
+  token;
+  branch;
+  fetchImpl;
+  commitMessagePrefix;
+  constructor(options) {
+    this.owner = options.owner;
+    this.repo = options.repo;
+    this.token = options.token;
+    this.branch = options.branch;
+    const fetchImpl = options.fetch ?? fetch;
+    this.fetchImpl = (input, init) => fetchImpl(input, init);
+    this.commitMessagePrefix = options.commitMessagePrefix ?? "shipbench:";
+  }
+  contentsUrl(path) {
+    return `${API_BASE}/repos/${this.owner}/${this.repo}/contents/${encodePath(path)}`;
+  }
+  contentsReadUrl(path) {
+    const url = this.contentsUrl(path);
+    return this.branch === void 0 ? url : `${url}?ref=${encodeURIComponent(this.branch)}`;
+  }
+  headers() {
+    return {
+      Authorization: `Bearer ${this.token}`,
+      Accept: "application/vnd.github.v3+json",
+      "X-GitHub-Api-Version": "2022-11-28",
+      "User-Agent": "@shipbench/core"
+    };
+  }
+  async errorFromResponse(res, operation, path) {
+    let body = "";
+    try {
+      body = await res.text();
+    } catch {
+    }
+    return new GitHubApiError({
+      status: res.status,
+      statusText: res.statusText,
+      operation,
+      path,
+      body
+    });
+  }
+  async readFileContent(path, missingAsNull) {
+    const url = this.contentsReadUrl(path);
+    const res = await this.fetchImpl(url, { headers: this.headers() });
+    if (missingAsNull && res.status === 404) return null;
+    if (!res.ok) throw await this.errorFromResponse(res, "readFile", path);
+    const json = await res.json();
+    if (Array.isArray(json)) {
+      throw new Error(
+        `GitHubAdapter.readFile: "${path}" is a directory, not a file.`
+      );
+    }
+    if (json.encoding !== "base64") {
+      throw new Error(
+        `GitHubAdapter.readFile: unexpected encoding "${json.encoding}" for "${path}".`
+      );
+    }
+    return base64ToUtf8(json.content);
+  }
+  async readFile(path) {
+    const content = await this.readFileContent(path, false);
+    return content;
+  }
+  async readFileIfExists(path) {
+    return this.readFileContent(path, true);
+  }
+  /** Returns the SHA of an existing file, or undefined if it does not exist. */
+  async getSha(path) {
+    const url = this.contentsReadUrl(path);
+    const res = await this.fetchImpl(url, { headers: this.headers() });
+    if (res.status === 404) return void 0;
+    if (!res.ok) throw await this.errorFromResponse(res, "getSha", path);
+    const json = await res.json();
+    if (Array.isArray(json)) {
+      throw new Error(
+        `GitHubAdapter.getSha: "${path}" is a directory, not a file.`
+      );
+    }
+    return json.sha;
+  }
+  async writeFile(path, content) {
+    const sha = await this.getSha(path);
+    const body = {
+      message: `${this.commitMessagePrefix} ${sha ? "update" : "create"} ${path}`,
+      content: utf8ToBase64(content)
+    };
+    if (this.branch !== void 0) body.branch = this.branch;
+    if (sha) body.sha = sha;
+    const res = await this.fetchImpl(this.contentsUrl(path), {
+      method: "PUT",
+      headers: { ...this.headers(), "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) throw await this.errorFromResponse(res, "writeFile", path);
+  }
+  async listFiles(directory) {
+    const url = this.contentsReadUrl(directory);
+    const res = await this.fetchImpl(url, { headers: this.headers() });
+    if (res.status === 404) return [];
+    if (!res.ok)
+      throw await this.errorFromResponse(res, "listFiles", directory);
+    const json = await res.json();
+    if (!Array.isArray(json)) {
+      throw new Error(
+        `GitHubAdapter.listFiles: "${directory}" is a file, not a directory.`
+      );
+    }
+    return json.filter((e) => e.type === "file").map((e) => e.name);
+  }
+  async readFiles(paths) {
+    const entries = await Promise.all(
+      paths.map(async (p) => [p, await this.readFile(p)])
+    );
+    return new Map(entries);
+  }
+  async writeFiles(files) {
+    for (const [path, content] of files) {
+      await this.writeFile(path, content);
+    }
+  }
+};
+
+// src/dependencies.ts
+function createTaskDependencyIndex(liveTasks, archivedTasks = [], archivedSlugs = []) {
+  return {
+    liveTasksBySlug: new Map(liveTasks.map((task) => [task.slug, task])),
+    archivedTasksBySlug: new Map(archivedTasks.map((task) => [task.slug, task])),
+    archivedSlugs: /* @__PURE__ */ new Set([
+      ...archivedSlugs,
+      ...archivedTasks.map((task) => task.slug)
+    ])
+  };
+}
+function dependencySlugs(task) {
+  const dependencies = task.frontmatter.depends_on;
+  if (dependencies === void 0) return [];
+  if (!Array.isArray(dependencies)) return null;
+  if (dependencies.some((dependency) => typeof dependency !== "string")) {
+    return null;
+  }
+  return [...new Set(dependencies)];
+}
+function resolveTaskDependency(slug, index) {
+  const liveTask = index.liveTasksBySlug.get(slug);
+  if (liveTask) {
+    return {
+      kind: "live",
+      status: liveTask.frontmatter.status,
+      task: liveTask
+    };
+  }
+  const archivedTask = index.archivedTasksBySlug.get(slug);
+  if (archivedTask) {
+    return { kind: "archived", status: "archived", task: archivedTask };
+  }
+  if (index.archivedSlugs.has(slug)) {
+    return { kind: "archived", status: "archived" };
+  }
+  return { kind: "missing", status: "missing" };
+}
+function dependencyStatus(slug, index) {
+  return resolveTaskDependency(slug, index).status;
+}
+function taskDependenciesAreSatisfied(task, index, doneColumn) {
+  const dependencies = dependencySlugs(task);
+  if (dependencies === null) return false;
+  return dependencies.every((dependency) => {
+    if (dependency === task.slug) return false;
+    const resolution = resolveTaskDependency(dependency, index);
+    return resolution.kind === "archived" || resolution.kind === "live" && resolution.status === doneColumn;
+  });
+}
+function buildTaskDependencyGraph(liveTasks, options = {}) {
+  const archivedTasks = options.archivedTasks ?? [];
+  const index = createTaskDependencyIndex(
+    liveTasks,
+    archivedTasks,
+    options.archivedSlugs
+  );
+  const nodes = /* @__PURE__ */ new Map();
+  const sourceTasks = [
+    ...liveTasks,
+    ...archivedTasks.filter((task) => !index.liveTasksBySlug.has(task.slug))
+  ];
+  for (const task of sourceTasks) {
+    nodes.set(task.slug, {
+      status: dependencyStatus(task.slug, index),
+      depends_on: dependencySlugs(task) ?? [],
+      blocks: []
+    });
+  }
+  for (const task of sourceTasks) {
+    const dependencies = dependencySlugs(task) ?? [];
+    for (const dependency of dependencies) {
+      const dependencyNode = nodes.get(dependency) ?? {
+        status: dependencyStatus(dependency, index),
+        depends_on: [],
+        blocks: []
+      };
+      dependencyNode.blocks.push(task.slug);
+      nodes.set(dependency, dependencyNode);
+    }
+  }
+  return Object.fromEntries(
+    [...nodes.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([slug, node]) => [
+      slug,
+      {
+        ...node,
+        blocks: [...new Set(node.blocks)].sort((a, b) => a.localeCompare(b))
+      }
+    ])
+  );
+}
+
+// src/availability.ts
+function compareTaskReadiness(a, b, config) {
+  const priorityRank = (task) => {
+    const priority = task.frontmatter.priority ?? config.priority.default;
+    return config.priority.values.indexOf(priority);
+  };
+  const priorityDifference = priorityRank(b) - priorityRank(a);
+  if (priorityDifference !== 0) return priorityDifference;
+  const aCreated = Date.parse(a.frontmatter.created);
+  const bCreated = Date.parse(b.frontmatter.created);
+  if (Number.isFinite(aCreated) && Number.isFinite(bCreated)) {
+    const createdDifference = aCreated - bCreated;
+    if (createdDifference !== 0) return createdDifference;
+  } else if (Number.isFinite(aCreated)) {
+    return -1;
+  } else if (Number.isFinite(bCreated)) {
+    return 1;
+  }
+  return a.slug.localeCompare(b.slug);
+}
+function listTasksByAvailability(tasks, config, mode, options = {}) {
+  const status = options.status ?? config.default_column;
+  const dependencyIndex = createTaskDependencyIndex(
+    tasks,
+    options.archivedTasks,
+    options.archivedSlugs
+  );
+  return tasks.filter((task) => {
+    if (task.frontmatter.status !== status) return false;
+    const available = taskDependenciesAreSatisfied(
+      task,
+      dependencyIndex,
+      config.done_column
+    );
+    return mode === "available" ? available : !available;
+  }).sort((a, b) => compareTaskReadiness(a, b, config));
+}
+function listAvailableTasks(tasks, config, options = {}) {
+  return listTasksByAvailability(tasks, config, "available", options);
+}
+function listBlockedTasks(tasks, config, options = {}) {
+  return listTasksByAvailability(tasks, config, "blocked", options);
+}
+
+// src/defaults.ts
+var DEFAULT_CONFIG = {
+  version: 1,
+  // Safety net for partial configs read via loadConfig's deep-merge. Fresh
+  // projects always override this with a real name at `shipbench init` time.
+  name: "Untitled Project",
+  columns: [
+    { id: "todo", label: "To Do" },
+    { id: "in-progress", label: "In Progress" },
+    { id: "done", label: "Done" }
+  ],
+  default_column: "todo",
+  done_column: "done",
+  done_display: {
+    max: 20
+  },
+  priority: {
+    values: ["low", "medium", "high"],
+    default: "medium"
+  },
+  schema: {
+    custom_fields: {}
+  },
+  layout: {}
+};
+
+// src/config.ts
+var CONFIG_PATH = ".shipbench/config.json";
+var LAYOUT_PATH = ".shipbench/layout.json";
+function assertLayoutShape(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("Layout must contain a JSON object.");
+  }
+  for (const [column, slugs] of Object.entries(value)) {
+    if (!Array.isArray(slugs) || slugs.some((slug) => typeof slug !== "string")) {
+      throw new Error(`Layout entry "${column}" must be an array of slugs.`);
+    }
+  }
+  return value;
+}
+function resolveLayout(raw, legacyLayout, columnIds, options) {
+  const source = raw === null ? CONFIG_PATH : LAYOUT_PATH;
+  let shaped;
+  try {
+    shaped = raw === null ? assertLayoutShape(legacyLayout ?? {}) : assertLayoutShape(JSON.parse(raw));
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : "Invalid layout.";
+    options.onWarning?.({
+      path: source,
+      message: `${detail} Manual ordering was ignored; using deterministic fallback order.`
+    });
+    return {};
+  }
+  const unknownKeys = Object.keys(shaped).filter((key) => !columnIds.has(key));
+  if (unknownKeys.length === 0) return shaped;
+  const pruned = {};
+  for (const [key, slugs] of Object.entries(shaped)) {
+    if (columnIds.has(key)) pruned[key] = slugs;
+  }
+  options.onWarning?.({
+    path: source,
+    message: `Layout key(s) ${unknownKeys.map((key) => `"${key}"`).join(", ")} do not match any configured column. Manual ordering for ${unknownKeys.length === 1 ? "that column" : "those columns"} was ignored; using deterministic fallback order there.`
+  });
+  return pruned;
+}
+function deepMerge(defaults, overrides) {
+  const result = { ...defaults };
+  for (const key of Object.keys(overrides)) {
+    const val = overrides[key];
+    if (val !== void 0 && typeof val === "object" && val !== null && !Array.isArray(val) && typeof result[key] === "object" && result[key] !== null && !Array.isArray(result[key])) {
+      result[key] = deepMerge(
+        result[key],
+        val
+      );
+    } else if (val !== void 0) {
+      result[key] = val;
+    }
+  }
+  return result;
+}
+async function loadConfig(adapter, options = {}) {
+  const raw = await adapter.readFile(CONFIG_PATH);
+  const parsedConfig = JSON.parse(raw);
+  if (typeof parsedConfig !== "object" || parsedConfig === null || Array.isArray(parsedConfig)) {
+    throw new Error("Config must contain a JSON object.");
+  }
+  const userConfig = parsedConfig;
+  const layoutRaw = await adapter.readFileIfExists(LAYOUT_PATH);
+  const legacyLayout = userConfig.layout;
+  const { layout: _layout, ...configOverrides } = userConfig;
+  const config = deepMerge(structuredClone(DEFAULT_CONFIG), configOverrides);
+  if (!Object.hasOwn(userConfig, "default_column")) {
+    const firstColumn = Array.isArray(config.columns) ? config.columns[0] : null;
+    config.default_column = firstColumn?.id ?? DEFAULT_CONFIG.default_column;
+  }
+  const columnIds = new Set(
+    Array.isArray(config.columns) ? config.columns.filter(
+      (column) => typeof column === "object" && column !== null && typeof column.id === "string"
+    ).map((column) => column.id) : []
+  );
+  config.layout = resolveLayout(layoutRaw, legacyLayout, columnIds, options);
+  const errors = validateConfig(config);
+  if (errors.length > 0) {
+    throw new Error(`Invalid ShipBench config: ${errors.join(" ")}`);
+  }
+  return config;
+}
+function validateConfig(config) {
+  const errors = [];
+  const candidate = config;
+  if (typeof candidate.name !== "string" || !candidate.name.trim()) {
+    errors.push("Config must define a non-empty name.");
+  }
+  const columns = Array.isArray(candidate.columns) ? candidate.columns : null;
+  if (!columns) {
+    errors.push("Config columns must be an array.");
+  } else if (!columns.length) {
+    errors.push("Config must define at least one column.");
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const duplicates = /* @__PURE__ */ new Set();
+  for (const [index, column] of (columns ?? []).entries()) {
+    if (typeof column !== "object" || column === null || Array.isArray(column)) {
+      errors.push(`Column ${index + 1} must be an object.`);
+      continue;
+    }
+    const id = column.id;
+    const label = column.label;
+    if (typeof id !== "string" || !id.trim()) {
+      errors.push(`Column ${index + 1} must define a non-empty id.`);
+      continue;
+    }
+    if (typeof label !== "string" || !label.trim()) {
+      errors.push(`Column "${id}" must define a non-empty label.`);
+    }
+    if (seen.has(id)) duplicates.add(id);
+    seen.add(id);
+  }
+  for (const id of duplicates) {
+    errors.push(`Duplicate column ID "${id}".`);
+  }
+  const columnIds = seen;
+  const defaultColumn = candidate.default_column;
+  const doneColumn = candidate.done_column;
+  if (typeof defaultColumn !== "string" || !columnIds.has(defaultColumn)) {
+    errors.push(
+      `default_column "${String(defaultColumn)}" does not match any column ID.`
+    );
+  }
+  if (typeof doneColumn !== "string" || !columnIds.has(doneColumn)) {
+    errors.push(
+      `done_column "${String(doneColumn)}" does not match any column ID.`
+    );
+  }
+  const priority = typeof candidate.priority === "object" && candidate.priority !== null && !Array.isArray(candidate.priority) ? candidate.priority : null;
+  const priorityValues = priority && Array.isArray(priority.values) ? priority.values.filter(
+    (value) => typeof value === "string"
+  ) : null;
+  if (!priorityValues || priorityValues.length !== priority?.values?.length) {
+    errors.push("priority.values must be an array of strings.");
+  }
+  if (!priority || typeof priority.default !== "string" || !priorityValues?.includes(priority.default)) {
+    errors.push(
+      `Default priority "${String(priority?.default)}" is not in the priority values list.`
+    );
+  }
+  const doneDisplay = typeof candidate.done_display === "object" && candidate.done_display !== null && !Array.isArray(candidate.done_display) ? candidate.done_display : null;
+  const doneMax = doneDisplay?.max;
+  if (typeof doneMax !== "number" || !Number.isFinite(doneMax) || !Number.isInteger(doneMax)) {
+    errors.push(
+      `done_display.max must be an integer (got ${JSON.stringify(doneMax)}).`
+    );
+  }
+  const layout = typeof candidate.layout === "object" && candidate.layout !== null && !Array.isArray(candidate.layout) ? candidate.layout : null;
+  if (!layout) {
+    errors.push("Layout must contain a JSON object.");
+  }
+  for (const [layoutKey, slugs] of Object.entries(layout ?? {})) {
+    if (!columnIds.has(layoutKey)) {
+      errors.push(`Layout key "${layoutKey}" does not match any column ID.`);
+    }
+    if (!Array.isArray(slugs) || slugs.some((slug) => typeof slug !== "string")) {
+      errors.push(`Layout entry "${layoutKey}" must be an array of slugs.`);
+    }
+  }
+  return errors;
+}
+
+// src/github-url.ts
+var GITHUB_URL_RE = /^https:\/\/github\.com\/([A-Za-z0-9][A-Za-z0-9._-]*)\/([A-Za-z0-9][A-Za-z0-9._-]*?)(?:\.git)?\/?$/;
+var GITHUB_SCP_REMOTE_RE = /^git@github\.com:([A-Za-z0-9][A-Za-z0-9._-]*)\/([A-Za-z0-9][A-Za-z0-9._-]*?)(?:\.git)?$/;
+var GITHUB_SSH_PATH_RE = /^\/([A-Za-z0-9][A-Za-z0-9._-]*)\/([A-Za-z0-9][A-Za-z0-9._-]*?)(?:\.git)?\/?$/;
+function validParts(owner, repo) {
+  return owner !== "." && owner !== ".." && repo !== "." && repo !== "..";
+}
+function parseGithubUrl(input) {
+  const match = GITHUB_URL_RE.exec(input.trim());
+  if (!match) return null;
+  const owner = match[1];
+  const repo = match[2];
+  return validParts(owner, repo) ? { owner, repo } : null;
+}
+function parseGithubRemoteUrl(input) {
+  const https = parseGithubUrl(input);
+  if (https) return https;
+  const trimmed = input.trim();
+  const scpMatch = GITHUB_SCP_REMOTE_RE.exec(trimmed);
+  if (scpMatch) {
+    const owner = scpMatch[1];
+    const repo = scpMatch[2];
+    return validParts(owner, repo) ? { owner, repo } : null;
+  }
+  try {
+    const url = new URL(trimmed);
+    if (url.protocol !== "ssh:" || url.hostname !== "github.com" || url.username !== "git" || url.password || url.port || url.search || url.hash) {
+      return null;
+    }
+    const pathMatch = GITHUB_SSH_PATH_RE.exec(url.pathname);
+    if (!pathMatch) return null;
+    const owner = pathMatch[1];
+    const repo = pathMatch[2];
+    return validParts(owner, repo) ? { owner, repo } : null;
+  } catch {
+    return null;
+  }
+}
+function normalizeGithubUrl(input) {
+  const parsed = parseGithubUrl(input);
+  return parsed ? `https://github.com/${parsed.owner}/${parsed.repo}` : null;
+}
+function normalizeGithubRemoteUrl(input) {
+  const parsed = parseGithubRemoteUrl(input);
+  return parsed ? `https://github.com/${parsed.owner}/${parsed.repo}` : null;
+}
+
+// src/tasks.ts
+import matter from "gray-matter";
+
+// src/slug.ts
+function slugify(title) {
+  return title.normalize("NFD").replace(/\p{Diacritic}/gu, "").toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+function resolveSlugCollision(slug, existingSlugs) {
+  if (!existingSlugs.has(slug)) return slug;
+  let counter = 2;
+  while (existingSlugs.has(`${slug}-${counter}`)) {
+    counter++;
+  }
+  return `${slug}-${counter}`;
+}
+
+// src/tasks.ts
+var TASKS_DIR = ".shipbench/tasks";
+var ARCHIVE_DIR = `${TASKS_DIR}/archive`;
+var CONFIG_PATH2 = ".shipbench/config.json";
+var LAYOUT_PATH2 = ".shipbench/layout.json";
+var UPDATES_HEADING = "## Task Updates";
+var ISO_8601_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+var updatesParseWarnings = /* @__PURE__ */ new WeakMap();
+var ArchiveBlockedError = class extends Error {
+  constructor(slug, dependentSlugs) {
+    super(
+      `Cannot archive "${slug}" because live tasks depend on it: ${dependentSlugs.join(", ")}`
+    );
+    this.slug = slug;
+    this.dependentSlugs = dependentSlugs;
+    this.name = "ArchiveBlockedError";
+  }
+  slug;
+  dependentSlugs;
+};
+var KNOWN_FRONTMATTER_FIELDS = /* @__PURE__ */ new Set([
+  "title",
+  "status",
+  "priority",
+  "assignee",
+  "tags",
+  "depends_on",
+  "created",
+  "updated"
+]);
+function normalizeTimestamp(v) {
+  return v instanceof Date ? v.toISOString() : v;
+}
+function updateFence(line, current) {
+  const match = line.match(/^\s{0,3}(`{3,}|~{3,})/);
+  if (!match) return current;
+  const sequence = match[1];
+  const marker = sequence[0];
+  if (!current) return { marker, length: sequence.length };
+  if (current.marker === marker && sequence.length >= current.length)
+    return null;
+  return current;
+}
+function malformedUpdates(body, detail) {
+  return {
+    body: body.trim(),
+    comments: [],
+    warning: `Malformed Updates section: ${detail} Raw Markdown was preserved in the task body.`
+  };
+}
+function parseTaskBody(rawBody) {
+  const body = rawBody.trim();
+  if (!body) return { body: "", comments: [] };
+  const lines = body.split(/\r?\n/);
+  const updatesHeadings = [];
+  let fence = null;
+  for (const [index, line] of lines.entries()) {
+    if (!fence && line.trimEnd() === UPDATES_HEADING) {
+      updatesHeadings.push(index);
+    }
+    fence = updateFence(line, fence);
+  }
+  if (updatesHeadings.length === 0) return { body, comments: [] };
+  if (updatesHeadings.length > 1) {
+    return malformedUpdates(
+      body,
+      `found more than one "${UPDATES_HEADING}" heading.`
+    );
+  }
+  const updatesIndex = updatesHeadings[0];
+  const description = lines.slice(0, updatesIndex).join("\n").trim();
+  const updateLines = lines.slice(updatesIndex + 1);
+  const comments = [];
+  let timestamp = null;
+  let textLines = [];
+  fence = null;
+  const finishComment = () => {
+    if (timestamp === null) return null;
+    const text = textLines.join("\n").trim();
+    if (!text) return `entry "${timestamp}" has no text.`;
+    comments.push({ timestamp, text });
+    return null;
+  };
+  for (const line of updateLines) {
+    const outsideFence = fence === null;
+    const fenceOnLine = /^\s{0,3}(`{3,}|~{3,})/.test(line);
+    if (outsideFence && !fenceOnLine) {
+      const heading = line.match(/^###\s+(.+?)\s*$/);
+      if (heading) {
+        const previousError = finishComment();
+        if (previousError) return malformedUpdates(body, previousError);
+        const nextTimestamp = heading[1];
+        if (!ISO_8601_TIMESTAMP.test(nextTimestamp) || Number.isNaN(Date.parse(nextTimestamp))) {
+          return malformedUpdates(
+            body,
+            `"${nextTimestamp}" is not an ISO 8601 timestamp.`
+          );
+        }
+        timestamp = nextTimestamp;
+        textLines = [];
+        continue;
+      }
+      if (/^#{1,6}(?:\s|$)/.test(line)) {
+        return malformedUpdates(
+          body,
+          `expected each entry heading to use "### <ISO 8601 timestamp>".`
+        );
+      }
+    }
+    if (timestamp === null) {
+      if (line.trim()) {
+        return malformedUpdates(
+          body,
+          `expected "### <ISO 8601 timestamp>" before entry text.`
+        );
+      }
+    } else {
+      textLines.push(line);
+    }
+    fence = updateFence(line, fence);
+  }
+  if (fence) {
+    return malformedUpdates(body, "an entry contains an unclosed code fence.");
+  }
+  const finalError = finishComment();
+  if (finalError) return malformedUpdates(body, finalError);
+  if (comments.length === 0) {
+    return malformedUpdates(body, "the section contains no entries.");
+  }
+  return { body: description, comments };
+}
+function parseFrontmatter(fileContent) {
+  try {
+    return matter(fileContent);
+  } catch (error) {
+    matter.clearCache();
+    throw error;
+  }
+}
+function parseTaskFile(slug, fileContent) {
+  const { data, content: bodyContent } = parseFrontmatter(fileContent);
+  const parsedBody = parseTaskBody(bodyContent);
+  const frontmatter = {
+    ...data,
+    created: normalizeTimestamp(data.created),
+    updated: normalizeTimestamp(data.updated)
+  };
+  const task = {
+    slug,
+    frontmatter,
+    body: parsedBody.body,
+    comments: parsedBody.comments
+  };
+  if (parsedBody.warning) {
+    updatesParseWarnings.set(task, parsedBody.warning);
+  }
+  return task;
+}
+function stripUndefined(obj) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== void 0) out[k] = v;
+  }
+  return out;
+}
+function serializeTask(task) {
+  const sections = [];
+  if (task.body.trim()) sections.push(task.body.trim());
+  if ((task.comments ?? []).length > 0) {
+    const entries = task.comments.map((comment) => `### ${comment.timestamp}
+${comment.text.trim()}`).join("\n\n");
+    sections.push(`${UPDATES_HEADING}
+
+${entries}`);
+  }
+  return matter.stringify(
+    `
+${sections.join("\n\n")}
+`,
+    stripUndefined(task.frontmatter)
+  );
+}
+function assertValidStatus(status, config) {
+  const valid = new Set(config.columns.map((c) => c.id));
+  if (!valid.has(status)) {
+    throw new Error(
+      `Invalid status "${status}". Valid: ${[...valid].join(", ")}`
+    );
+  }
+}
+function assertValidPriority(priority, config) {
+  if (!config.priority.values.includes(priority)) {
+    throw new Error(
+      `Invalid priority "${priority}". Valid: ${config.priority.values.join(", ")}`
+    );
+  }
+}
+function normalizeDependsOn(value) {
+  if (!value) return void 0;
+  const deduped = [...new Set(value.map((s) => s.trim()).filter(Boolean))];
+  return deduped.length > 0 ? deduped : void 0;
+}
+async function assertValidDependsOn(adapter, config, slug, dependsOn) {
+  if (!dependsOn || dependsOn.length === 0) return;
+  if (dependsOn.includes(slug)) {
+    throw new Error(`Task "${slug}" cannot depend on itself.`);
+  }
+  const { tasks } = await listTasks(adapter, config);
+  const bySlug = new Map(tasks.map((t) => [t.slug, t]));
+  for (const dep of dependsOn) {
+    const target = bySlug.get(dep);
+    if (!target) {
+      throw new Error(
+        `Unknown dependency "${dep}" \u2014 no task file matches that slug.`
+      );
+    }
+    if (target.frontmatter.depends_on?.includes(slug)) {
+      throw new Error(
+        `Dependency cycle: "${dep}" already depends on "${slug}".`
+      );
+    }
+  }
+}
+function validateTask(task, config, knownSlugs) {
+  const warnings = [];
+  const validStatuses = new Set(config.columns.map((c) => c.id));
+  const updatesWarning = updatesParseWarnings.get(task);
+  if (updatesWarning) {
+    warnings.push({
+      slug: task.slug,
+      field: "updates",
+      message: updatesWarning
+    });
+  }
+  if (!validStatuses.has(task.frontmatter.status)) {
+    warnings.push({
+      slug: task.slug,
+      field: "status",
+      message: `Unknown status "${task.frontmatter.status}". Valid: ${[...validStatuses].join(", ")}`
+    });
+  }
+  if (task.frontmatter.priority && !config.priority.values.includes(task.frontmatter.priority)) {
+    warnings.push({
+      slug: task.slug,
+      field: "priority",
+      message: `Unknown priority "${task.frontmatter.priority}". Valid: ${config.priority.values.join(", ")}`
+    });
+  }
+  const dependsOn = task.frontmatter.depends_on;
+  if (dependsOn !== void 0 && !Array.isArray(dependsOn)) {
+    warnings.push({
+      slug: task.slug,
+      field: "depends_on",
+      message: "Expected depends_on to be a list of task slugs."
+    });
+  } else if (dependsOn) {
+    for (const dep of dependsOn) {
+      if (!knownSlugs.has(dep)) {
+        warnings.push({
+          slug: task.slug,
+          field: "depends_on",
+          message: `Dangling dependency "${dep}" \u2014 no live task file matches that slug (it may be archived).`
+        });
+      }
+    }
+  }
+  for (const field of Object.keys(task.frontmatter)) {
+    if (!KNOWN_FRONTMATTER_FIELDS.has(field)) {
+      warnings.push({
+        slug: task.slug,
+        field,
+        message: `Unknown frontmatter field "${field}" (preserved).`
+      });
+    }
+  }
+  return warnings;
+}
+async function listTasksInDirectory(adapter, config, directory, additionalKnownSlugs = []) {
+  const files = await adapter.listFiles(directory);
+  const mdFiles = files.filter((f) => f.endsWith(".md"));
+  if (mdFiles.length === 0) {
+    return { tasks: [], warnings: [] };
+  }
+  const paths = mdFiles.map((f) => `${directory}/${f}`);
+  const contents = await adapter.readFiles(paths);
+  const tasks = [];
+  const warnings = [];
+  for (const [path, content] of contents) {
+    const slug = path.replace(`${directory}/`, "").replace(/\.md$/, "");
+    try {
+      tasks.push(parseTaskFile(slug, content));
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      warnings.push({
+        slug,
+        field: "frontmatter",
+        message: `Could not parse frontmatter in "${path}": ${detail}`
+      });
+    }
+  }
+  const knownSlugs = /* @__PURE__ */ new Set([
+    ...await additionalKnownSlugs,
+    ...mdFiles.map((file) => file.replace(/\.md$/, ""))
+  ]);
+  for (const task of tasks) {
+    warnings.push(...validateTask(task, config, knownSlugs));
+  }
+  return { tasks, warnings };
+}
+async function listTasks(adapter, config, options = {}) {
+  const archivedSlugs = Promise.all([
+    Promise.resolve(options.archivedTasks ?? []),
+    Promise.resolve(options.archivedSlugs ?? [])
+  ]).then(([tasks, fileSlugs]) => [
+    ...tasks.map((task) => task.slug),
+    ...fileSlugs
+  ]);
+  return listTasksInDirectory(adapter, config, TASKS_DIR, archivedSlugs);
+}
+async function getTask(adapter, config, slug, options = {}) {
+  void config;
+  const directory = options.archived ? ARCHIVE_DIR : TASKS_DIR;
+  const content = await adapter.readFileIfExists(`${directory}/${slug}.md`);
+  return content === null ? null : parseTaskFile(slug, content);
+}
+async function listArchivedTasks(adapter, config) {
+  const liveFiles = await adapter.listFiles(TASKS_DIR);
+  const liveSlugs = liveFiles.filter((file) => file.endsWith(".md")).map((file) => file.replace(/\.md$/, ""));
+  return listTasksInDirectory(adapter, config, ARCHIVE_DIR, liveSlugs);
+}
+function taskFileSlugs(result) {
+  return [
+    .../* @__PURE__ */ new Set([
+      ...result.tasks.map((task) => task.slug),
+      ...result.warnings.map((warning) => warning.slug)
+    ])
+  ];
+}
+async function createTask(adapter, config, title, fields) {
+  const [existingFiles, archivedFiles] = await Promise.all([
+    adapter.listFiles(TASKS_DIR),
+    adapter.listFiles(ARCHIVE_DIR)
+  ]);
+  const existingSlugs = new Set(
+    [...existingFiles, ...archivedFiles].filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, ""))
+  );
+  const baseSlug = slugify(title);
+  if (!baseSlug) {
+    throw new Error(
+      "Task title must contain at least one slug-able character."
+    );
+  }
+  const slug = resolveSlugCollision(baseSlug, existingSlugs);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const status = fields?.status ?? config.default_column;
+  assertValidStatus(status, config);
+  const priority = fields?.priority ?? config.priority.default;
+  assertValidPriority(priority, config);
+  const dependsOn = normalizeDependsOn(fields?.depends_on);
+  await assertValidDependsOn(adapter, config, slug, dependsOn);
+  const task = {
+    slug,
+    frontmatter: {
+      title,
+      status,
+      priority,
+      assignee: fields?.assignee,
+      tags: fields?.tags,
+      depends_on: dependsOn,
+      created: now,
+      updated: now
+    },
+    body: "",
+    comments: []
+  };
+  await adapter.writeFile(`${TASKS_DIR}/${slug}.md`, serializeTask(task));
+  const currentLayout = config.layout ?? {};
+  const columnOrder = currentLayout[status] ?? [];
+  const nextLayout = status === config.done_column ? currentLayout : {
+    ...currentLayout,
+    [status]: [...columnOrder, slug]
+  };
+  await writeLayout(adapter, config, nextLayout);
+  return task;
+}
+async function updateTask(adapter, config, slug, fields, body) {
+  const path = `${TASKS_DIR}/${slug}.md`;
+  const content = await adapter.readFile(path);
+  const task = parseTaskFile(slug, content);
+  if (fields.status) assertValidStatus(fields.status, config);
+  if (fields.priority) assertValidPriority(fields.priority, config);
+  const dependsOnProvided = "depends_on" in fields;
+  const dependsOn = dependsOnProvided ? normalizeDependsOn(fields.depends_on) : void 0;
+  if (dependsOnProvided) {
+    await assertValidDependsOn(adapter, config, slug, dependsOn);
+  }
+  const statusChanged = fields.status !== void 0 && fields.status !== task.frontmatter.status;
+  task.frontmatter = {
+    ...task.frontmatter,
+    ...fields,
+    ...dependsOnProvided ? { depends_on: dependsOn } : {},
+    // `created` is set once at creation and is not user-modifiable.
+    created: task.frontmatter.created,
+    updated: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  if (body !== void 0) {
+    task.body = body;
+  }
+  await adapter.writeFile(path, serializeTask(task));
+  if (statusChanged) {
+    const layout = await reorderLayout(
+      adapter,
+      config,
+      slug,
+      task.frontmatter.status,
+      -1
+    );
+    return { task, layout };
+  }
+  return { task };
+}
+async function addComment(adapter, config, slug, text) {
+  void config;
+  const normalizedText = text.trim();
+  if (!normalizedText) {
+    throw new Error("Task update text must not be blank.");
+  }
+  const path = `${TASKS_DIR}/${slug}.md`;
+  const content = await adapter.readFile(path);
+  const task = parseTaskFile(slug, content);
+  if (updatesParseWarnings.has(task)) {
+    throw new Error(
+      `Cannot add an update to "${slug}" because its Updates section is malformed. Fix the section in the task file first.`
+    );
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  task.comments.push({ timestamp: now, text: normalizedText });
+  task.frontmatter.updated = now;
+  await adapter.writeFile(path, serializeTask(task));
+  return task;
+}
+function assertMutableComments(task, slug, action) {
+  if (updatesParseWarnings.has(task)) {
+    throw new Error(
+      `Cannot ${action} an update on "${slug}" because its Updates section is malformed. Fix the section in the task file first.`
+    );
+  }
+}
+function assertCommentIndex(task, slug, index) {
+  if (!Number.isInteger(index) || index < 0 || index >= task.comments.length) {
+    const expected = task.comments.length === 0 ? "the task has no Updates entries" : `expected a zero-based index from 0 to ${task.comments.length - 1}`;
+    throw new Error(
+      `Invalid task update index ${index} for "${slug}": ${expected}.`
+    );
+  }
+}
+async function editComment(adapter, config, slug, index, text) {
+  void config;
+  const normalizedText = text.trim();
+  if (!normalizedText) {
+    throw new Error("Task update text must not be blank.");
+  }
+  const path = `${TASKS_DIR}/${slug}.md`;
+  const content = await adapter.readFile(path);
+  const task = parseTaskFile(slug, content);
+  assertMutableComments(task, slug, "edit");
+  assertCommentIndex(task, slug, index);
+  const comment = task.comments[index];
+  task.comments[index] = { ...comment, text: normalizedText };
+  task.frontmatter.updated = (/* @__PURE__ */ new Date()).toISOString();
+  await adapter.writeFile(path, serializeTask(task));
+  return task;
+}
+async function deleteComment(adapter, config, slug, index) {
+  void config;
+  const path = `${TASKS_DIR}/${slug}.md`;
+  const content = await adapter.readFile(path);
+  const task = parseTaskFile(slug, content);
+  assertMutableComments(task, slug, "delete");
+  assertCommentIndex(task, slug, index);
+  task.comments.splice(index, 1);
+  task.frontmatter.updated = (/* @__PURE__ */ new Date()).toISOString();
+  await adapter.writeFile(path, serializeTask(task));
+  return task;
+}
+async function listExistingSlugs(adapter) {
+  const files = await adapter.listFiles(TASKS_DIR);
+  return new Set(
+    files.filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, ""))
+  );
+}
+function layoutWithoutDoneColumn(layout, doneColumn) {
+  const next = { ...layout };
+  delete next[doneColumn];
+  return next;
+}
+async function writeLayout(adapter, config, layout) {
+  const persistedLayout = layoutWithoutDoneColumn(layout, config.done_column);
+  const serializedLayout = `${JSON.stringify(persistedLayout, null, 2)}
+`;
+  const rawConfig = await adapter.readFile(CONFIG_PATH2);
+  const userConfig = JSON.parse(rawConfig);
+  if (Object.hasOwn(userConfig, "layout")) {
+    delete userConfig.layout;
+    await adapter.writeFiles(
+      /* @__PURE__ */ new Map([
+        [LAYOUT_PATH2, serializedLayout],
+        [CONFIG_PATH2, `${JSON.stringify(userConfig, null, 2)}
+`]
+      ])
+    );
+  } else {
+    await adapter.writeFile(LAYOUT_PATH2, serializedLayout);
+  }
+  return persistedLayout;
+}
+async function reorderTask(adapter, config, slug, toStatus, position) {
+  assertValidStatus(toStatus, config);
+  const path = `${TASKS_DIR}/${slug}.md`;
+  const content = await adapter.readFile(path);
+  const task = parseTaskFile(slug, content);
+  if (task.frontmatter.status !== toStatus) {
+    task.frontmatter = {
+      ...task.frontmatter,
+      status: toStatus,
+      updated: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await adapter.writeFile(path, serializeTask(task));
+  }
+  const layout = await reorderLayout(adapter, config, slug, toStatus, position);
+  return { task, layout };
+}
+async function reorderLayout(adapter, config, slug, toStatus, position) {
+  const { tasks: allTasks } = await listTasks(adapter, config);
+  return writeLayout(
+    adapter,
+    config,
+    layoutAfterMove({
+      layout: config.layout ?? {},
+      tasks: allTasks,
+      slug,
+      toStatus,
+      position,
+      doneColumn: config.done_column
+    })
+  );
+}
+async function moveTask(adapter, config, slug, toStatus) {
+  const { task } = await reorderTask(adapter, config, slug, toStatus, -1);
+  return task;
+}
+async function deleteTask(adapter, config, slug) {
+  await adapter.deleteFile(`${TASKS_DIR}/${slug}.md`);
+  const existingSlugs = await listExistingSlugs(adapter);
+  const layout = layoutWithoutTask(config.layout ?? {}, slug, existingSlugs);
+  await writeLayout(adapter, config, layout);
+}
+async function archiveTask(adapter, config, slug, options) {
+  const livePath = `${TASKS_DIR}/${slug}.md`;
+  const content = await adapter.readFile(livePath);
+  const task = parseTaskFile(slug, content);
+  if (task.frontmatter.status !== config.done_column && !options?.force) {
+    const { tasks } = await listTasks(adapter, config);
+    const dependentSlugs = tasks.filter(
+      (candidate) => candidate.slug !== slug && candidate.frontmatter.depends_on?.includes(slug)
+    ).map((candidate) => candidate.slug).sort();
+    if (dependentSlugs.length > 0) {
+      throw new ArchiveBlockedError(slug, dependentSlugs);
+    }
+  }
+  await adapter.writeFile(`${ARCHIVE_DIR}/${slug}.md`, content);
+  await adapter.deleteFile(livePath);
+  const existingSlugs = await listExistingSlugs(adapter);
+  const layout = layoutWithoutTask(config.layout ?? {}, slug, existingSlugs);
+  const currentPersistedLayout = layoutWithoutDoneColumn(
+    config.layout ?? {},
+    config.done_column
+  );
+  if (JSON.stringify(layout) !== JSON.stringify(currentPersistedLayout)) {
+    await writeLayout(adapter, config, layout);
+  }
+  return task;
+}
+async function unarchiveTask(adapter, config, slug) {
+  const archivedPath = `${ARCHIVE_DIR}/${slug}.md`;
+  const content = await adapter.readFile(archivedPath);
+  const task = parseTaskFile(slug, content);
+  await adapter.writeFile(`${TASKS_DIR}/${slug}.md`, content);
+  await adapter.deleteFile(archivedPath);
+  const status = task.frontmatter.status;
+  if (status !== config.done_column) {
+    const existingSlugs = await listExistingSlugs(adapter);
+    const currentLayout = layoutWithoutTask(
+      config.layout ?? {},
+      slug,
+      existingSlugs
+    );
+    const nextLayout = {
+      ...currentLayout,
+      [status]: [...currentLayout[status] ?? [], slug]
+    };
+    await writeLayout(adapter, config, nextLayout);
+  }
+  return task;
+}
+
+// src/init.ts
+var ProjectInitializationError = class extends Error {
+  constructor(state) {
+    super(formatProjectInitializationError(state));
+    this.state = state;
+    this.name = "ProjectInitializationError";
+  }
+  state;
+};
+var CONFIG_PATH3 = ".shipbench/config.json";
+var LAYOUT_PATH3 = ".shipbench/layout.json";
+var README_PATH = ".shipbench/README.md";
+var AGENTS_PATH = ".shipbench/AGENTS.md";
+var TASKS_DIR2 = ".shipbench/tasks";
+var ARCHIVE_DIR2 = `${TASKS_DIR2}/archive`;
+function formatProjectInitializationError(state) {
+  if (state.kind === "incomplete") {
+    return `ShipBench project is incomplete: ${CONFIG_PATH3} is missing while these project files exist: ${state.paths.join(", ")}. Restore the config or move the partial .shipbench directory aside before retrying.`;
+  }
+  const label = state.kind === "malformed" ? "malformed" : "invalid";
+  return `ShipBench project is ${label}: ${state.errors.join(" ")}`;
+}
+function parseJsonObject(raw, label) {
+  try {
+    const value = JSON.parse(raw);
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      return { error: `${label} must contain a JSON object.` };
+    }
+    return { value };
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : "Invalid JSON.";
+    return { error: `${label} contains malformed JSON: ${detail}` };
+  }
+}
+async function findPartialProjectPaths(adapter) {
+  const [readme, agents, layout, liveFiles, archivedFiles] = await Promise.all([
+    adapter.readFileIfExists(README_PATH),
+    adapter.readFileIfExists(AGENTS_PATH),
+    adapter.readFileIfExists(LAYOUT_PATH3),
+    adapter.listFiles(TASKS_DIR2),
+    adapter.listFiles(ARCHIVE_DIR2)
+  ]);
+  const paths = [];
+  if (readme !== null) paths.push(README_PATH);
+  if (agents !== null) paths.push(AGENTS_PATH);
+  if (layout !== null) paths.push(LAYOUT_PATH3);
+  paths.push(
+    ...liveFiles.filter((file) => file.endsWith(".md")).map((file) => `${TASKS_DIR2}/${file}`),
+    ...archivedFiles.filter((file) => file.endsWith(".md")).map((file) => `${ARCHIVE_DIR2}/${file}`)
+  );
+  return [...new Set(paths)].sort();
+}
+async function inspectProjectInitialization(adapter) {
+  const rawConfig = await adapter.readFileIfExists(CONFIG_PATH3);
+  if (rawConfig === null) {
+    const paths = await findPartialProjectPaths(adapter);
+    return paths.length > 0 ? { kind: "incomplete", paths } : { kind: "missing" };
+  }
+  const parsedConfig = parseJsonObject(rawConfig, "config.json");
+  if ("error" in parsedConfig) {
+    return { kind: "malformed", errors: [parsedConfig.error] };
+  }
+  let config;
+  const configWarnings = [];
+  try {
+    config = await loadConfig(adapter, {
+      onWarning: (warning) => {
+        configWarnings.push(warning);
+      }
+    });
+  } catch (error) {
+    return {
+      kind: "invalid",
+      errors: [
+        error instanceof Error ? error.message : "Could not resolve ShipBench configuration."
+      ]
+    };
+  }
+  try {
+    const { warnings } = await listTasks(adapter, config);
+    return {
+      kind: "initialized",
+      config,
+      warnings: [...configWarnings, ...warnings]
+    };
+  } catch (error) {
+    return {
+      kind: "invalid",
+      errors: [
+        `Could not read ShipBench tasks: ${error instanceof Error ? error.message : "Unknown task read error."}`
+      ]
+    };
+  }
+}
+function generateReadme(name) {
+  return `# ${name} \u2014 ShipBench Project Board
+
+This directory contains the ShipBench project board for **${name}**. Everything lives in Git alongside your code \u2014 no external service required.
+
+## Structure
+
+- \`config.json\` \u2014 Human-owned board configuration (columns, priorities, schema)
+- \`layout.json\` \u2014 Machine-managed partial index of manual placements
+- \`tasks/\` \u2014 Individual task files as Markdown with YAML frontmatter
+- \`tasks/archive/\` \u2014 Archived task files, kept byte-for-byte for later restore
+- \`README.md\` \u2014 This file. Human-facing reference for the board configuration.
+- \`AGENTS.md\` \u2014 Machine-facing reference for autonomous agents
+
+## Working with the board
+
+Tasks can be managed through any combination of:
+
+- **The ShipBench CLI** (\`shipbench\` commands) \u2014 recommended for scripted or agent-driven changes; centralizes slug generation, validation, timestamps, and layout updates.
+- **The Board UI** (\`shipbench board\`) \u2014 local kanban in your browser, with live file watching.
+- **The terminal board** (\`shipbench board terminal\`) \u2014 the same board as a read-only live view, for leaving open in a pane beside your work.
+- **Harbor** \u2014 hosted view for browsing project boards across repos.
+- **Direct file editing** \u2014 always valid; task files are plain Markdown.
+
+## \`config.json\` reference
+
+Every field has a sensible default. \`config.json\` is deep-merged over ShipBench's built-in defaults on read, so you can delete any block you don't care about and it will fall back to default behavior. \`shipbench init\` scaffolds the full file for discoverability.
+
+### \`version\`
+
+Schema version. Currently informational. Leave as \`1\`.
+
+### \`name\`
+
+The project's display name. Every consumer (CLI, Board, Harbor) reads this for the breadcrumb root. Defaults to the basename of the current directory when \`shipbench init\` runs; override with \`--name\`.
+
+### \`columns\`
+
+The source of truth for valid task \`status\` values. Each entry is:
+
+- \`id\` \u2014 used verbatim in task frontmatter \`status\` fields.
+- \`label\` \u2014 what the Board UI displays as the column header.
+
+Add a column by appending to the array (e.g. \`{ "id": "review", "label": "Review" }\`). Tasks that reference a column ID that no longer exists surface in an "Uncategorized" column on the board \u2014 they're never dropped.
+
+### \`default_column\`
+
+The column ID used when a task is created without an explicit \`status\` (\`shipbench task create "..."\`, the Board's new-task dialog). Must reference an existing column ID. If omitted, falls back to the first column in \`columns\`.
+
+### \`done_column\`
+
+The single column ID that represents task completion. Two behaviors ride on this:
+
+- The board ignores manual \`layout\` order for this column and time-sorts by \`updated\` desc (most-recently-touched at the top). Within-column drag reorder is disabled.
+- \`done_display\` (below) applies to it.
+
+### \`done_display\`
+
+Controls how the done column is rendered.
+
+- \`max\` \u2014 number of most-recent done tasks shown by default. Older tasks live behind a \`Show N more\` toggle. Set to \`0\` (or any negative number) to disable the cap and show everything. Search bypasses the cap so hidden matches remain findable.
+
+Omit \`done_display\` to fall back to \`{ "max": 20 }\`.
+
+### \`priority\`
+
+- \`values\` \u2014 the allowed \`priority\` values for task frontmatter.
+- \`default\` \u2014 the value assigned when a task is created without a priority. Must appear in \`values\`.
+
+Priority is optional on individual tasks; it just needs to match \`values\` when set.
+
+### \`schema.custom_fields\`
+
+Reserved for future user-defined frontmatter fields. Ignored today. Safe to leave as \`{}\`.
+
+## \`layout.json\`
+
+\`layout.json\` is a partial, machine-managed index of manual placements. It is not a complete snapshot of visible board order: it can omit whole columns and unlisted tasks, never retains \`done_column\`, may carry stale slugs until a relevant write prunes them, and may be absent or gitignored.
+
+Visible order comes from \`config.json\`, the task files, and this partial index together:
+
+- Configured columns render in \`config.columns\` order, followed by Uncategorized tasks.
+- Tasks whose slug appears in \`layout[columnId]\` render in that order.
+- Tasks with a matching status but no layout entry render below, sorted by \`created\` desc.
+- Slugs in \`layout\` that don't correspond to a task on disk are ignored at render time.
+- The Uncategorized column and the \`done_column\` both ignore \`layout\` entirely.
+- The CLI and Board do not record \`layout[done_column]\`; any existing entry is removed on the next layout write.
+
+Do not read \`layout.json\` alone to determine board order. \`shipbench task list\` returns live tasks in canonical board order, and its JSON output includes each task's zero-based \`position\` within its column. Code clients can apply \`orderedTasksForColumn\` to the task files. Treat the index as machine-managed: do not hand-edit or hand-order it. You may gitignore it if ordering should stay machine-local, but Harbor and fresh clones will then fall back to deterministic \`created\`-descending order for unlisted tasks.
+
+## Task files
+
+Every file in \`tasks/\` is a Markdown document with a YAML frontmatter block. See \`AGENTS.md\` for the frontmatter schema and field rules \u2014 the same rules apply whether a human or an agent is editing.
+
+Read the narrowest thing that answers the question. Because each task has a slug, read one task when one task is enough. Use list, search, or archive reads only for broader questions.
+
+Each task may end with a reserved \`## Task Updates\` section. Use it for time-anchored decisions, pivots, and external events that would lose meaning without their timestamp. Keep timeless facts in the description instead. Append with \`shipbench task comment <slug> "What changed and why."\`, edit text with \`shipbench task comment edit <slug> <index> "Corrected text."\`, or delete with \`shipbench task comment delete <slug> <index>\`. Indices are zero-based. Edits preserve the entry's timestamp; Git preserves earlier text and deleted entries.
+
+Archived tasks live in \`tasks/archive/\` and are excluded from normal board reads. Archiving moves the file without changing its frontmatter or timestamps; unarchiving restores the same file to \`tasks/\`.
+`;
+}
+function generateAgentsMd(name) {
+  const config = DEFAULT_CONFIG;
+  const validStatuses = config.columns.map((c) => c.id).join(", ");
+  const validPriorities = config.priority.values.join(", ");
+  return `# ${name} \u2014 ShipBench Agent Instructions
+
+This file describes how to interact with the ShipBench task board for **${name}**.
+
+## Directory Structure
+
+\`\`\`
+.shipbench/
+  config.json          # Board configuration \u2014 read this for valid values
+  layout.json          # Partial placement index \u2014 do not read as visible order
+  tasks/               # One Markdown file per task
+    <slug>.md
+    archive/            # Archived tasks \u2014 do not read unless asked
+      <slug>.md
+\`\`\`
+
+## Task File Format
+
+Each task is a Markdown file with YAML frontmatter:
+
+\`\`\`markdown
+---
+title: Task title here
+status: todo
+priority: medium
+assignee:
+tags: []
+depends_on: []
+created: 2024-01-01T00:00:00.000Z
+updated: 2024-01-01T00:00:00.000Z
+---
+
+Task description in Markdown.
+\`\`\`
+
+## Field Rules
+
+- **title** (required): Display name of the task.
+- **status** (required): Must be one of: ${validStatuses}. Read \`config.json\` columns for current valid values.
+- **priority** (optional): Must be one of: ${validPriorities}. Defaults to "${config.priority.default}".
+- **assignee** (optional): Freeform string label (e.g. \`claude\`, \`antigravity\`, or \`human\`). Informational only \u2014 task eligibility is governed strictly by \`status\` and \`depends_on\`. Moving a task to \`in-progress\` signals that work has started.
+- **tags** (optional): Array of freeform strings.
+- **depends_on** (optional): Array of task slugs that must be finished before this task can start. An omitted field and an empty array mean the same thing. A slug must name a task file that exists; a task may not depend on itself, and two tasks may not depend on each other.
+- **created** (required): ISO 8601 timestamp. Set once on creation, never modify.
+- **updated** (required): ISO 8601 timestamp. Update on every modification.
+
+## Task Updates
+
+A task may end with a reserved \`## Task Updates\` section containing timestamped entries:
+
+\`\`\`markdown
+## Task Updates
+
+### 2026-07-24T20:00:00.000Z
+Raised priority after the customer escalation.
+\`\`\`
+
+Before adding an entry, ask: **Would this fact still be true or relevant regardless of when it happened?** If yes, edit the task description in place. If its meaning depends on a moment \u2014 a decision, pivot, scope change, or external event \u2014 add an Update.
+
+This heuristic is guidance, not a validation rule. Core stores each entry as \`{ timestamp, text }\` and never judges or reformats the prose. A project may use Updates as a general comments log if that serves its workflow.
+
+Append through \`shipbench task comment <slug> "What changed and why."\`. Edit text with \`shipbench task comment edit <slug> <index> "Corrected text."\`; delete an entry with \`shipbench task comment delete <slug> <index>\`. Indices are zero-based. Editing never changes the entry's timestamp. Git preserves earlier text and deleted entries.
+
+Do not hand-edit content below the \`## Task Updates\` marker when the CLI is available.
+
+## Choosing What to Work On
+
+Read the narrowest thing that answers your question. Because each task has a slug, use a body-free list or search to narrow the candidates, then run \`task get\` or read one \`.shipbench/tasks/<slug>.md\` file. Read multiple descriptions or archived tasks only when needed.
+
+\`depends_on\` is the authoritative dependency signal. Start with this read-only query:
+
+\`\`\`bash
+shipbench task list --available --json
+\`\`\`
+
+\`--available\` selects tasks from the configured default column whose dependencies are all in the \`${config.done_column}\` column or \`tasks/archive/\`. Archived dependencies count as satisfied. Results are ranked by configured priority, then oldest creation time, so the first result is a useful candidate rather than a mandatory assignment.
+
+That ranking is not the board's order. \`--available\` sorts by priority and age and does not read manual placement, while a plain \`shipbench task list\` returns the order the columns are actually arranged in. The two can disagree \u2014 a task sitting first in its column may come back third here \u2014 and neither is the more correct answer. JSON carries both: the array is in ranked order, and each task's \`position\` is its board placement, computed before the ranking. Read whichever answers the question you have.
+
+Narrow the candidate set without loading every description:
+
+\`\`\`bash
+shipbench task list --available --tag backend --json
+shipbench task list --available --tag backend,auth --assignee agent --json
+\`\`\`
+
+\`--tag\` accepts comma-separated values or repeated flags and uses AND semantics. \`--status\`, \`--assignee\`, \`--priority\`, and \`--limit\` can narrow the same query. Use \`--status\` when the project's actionable column differs from its configured default.
+
+After selecting a slug, load that task's full frontmatter, description, and Updates:
+
+\`\`\`bash
+shipbench task get <slug>
+\`\`\`
+
+Use the other discovery commands when the task needs more context:
+
+- **Diagnose blocked work**: \`shipbench task list --blocked --json\`
+- **Search titles, tags, and descriptions**: \`shipbench task search "<query>" --json\`
+- **Load complete matching descriptions**: \`shipbench task search "<query>" --json --include-body\`
+- **Search live and archived tasks**: \`shipbench task search "<query>" --all --json\`
+- **Inspect the dependency DAG**: \`shipbench task graph --json\` (add \`--archived\` to resolve archived nodes)
+- **List archived tasks**: \`shipbench task list --archived --json\`
+
+Following that principle, add \`--include-body\` to a JSON \`task list\` only when you need every returned description and Updates array. Add it to a JSON \`task search\` when you need complete matching descriptions instead of snippets. Prefer \`task get\` after narrowing when one matching task answers the question.
+
+\`--available\` and \`--blocked\` are mutually exclusive and cannot be combined with \`--archived\`.
+
+A task with unfinished dependencies is not ready, even if nothing prevents you from editing it \u2014 \`depends_on\` is data, not a lock.
+
+Prose sections in a task body (\`## Depends on\`, \`## Blocked by\`, and similar) are commentary. Read them for context, but do not treat them as the dependency graph.
+
+Note that \`depends_on\` and the task's column are orthogonal. A column says where a task is; \`depends_on\` says what has to land first.
+
+## Reading Board Order
+
+\`layout.json\` is a partial, machine-managed index, not the visible order. It can omit \`done_column\`, unlisted tasks, and whole columns; retain stale slugs until another layout write; or be absent or gitignored. Reading it alone can therefore give the wrong answer.
+
+\`shipbench task list\` reports live tasks in configured column order and visible within-column order; JSON output includes each task's zero-based \`position\` within its column. Code clients can apply \`orderedTasksForColumn\` to the task files. When working directly with the plain files, combine task statuses with \`config.json\` and the ordering rules in \`README.md\`; do not use \`layout.json\` alone as the answer.
+
+## Changing Board Order
+
+\`shipbench task move\` accepts placement flags \u2014 \`--top\`, \`--bottom\`, \`--before <slug>\`, \`--after <slug>\`, and \`--position <n>\` (0-based, \`-1\` appends) \u2014 and \`--to\` is optional, so omitting it reorders within the task's current column. Anchors are the clearer interface: \`--before build-api\` states an intent, while a raw index depends on what the column looks like right now. Placement flags are mutually exclusive and cannot target the done column, which is always sorted by \`updated\` desc.
+
+This is the only sanctioned way to reorder. \`layout.json\` stays off-limits to hand edits.
+
+Ordering is a human judgment call, so reorder only when the user explicitly asks \u2014 never as a side effect of other board work, the same posture as \`task delete\`.
+
+## File Naming
+
+- Filenames are slugified from the title: lowercase, hyphens for non-slug characters, no special characters.
+- If a slug already exists in either \`tasks/\` or \`tasks/archive/\`, append a numeric suffix: \`my-task-2.md\`. Archived slugs are never reused.
+
+## Operations
+
+Prefer the ShipBench CLI for task mutations when it is available. The CLI routes through core, so slug generation, validation, timestamps, collision handling, and layout updates stay consistent.
+
+### Preferred CLI Operations
+
+- **List available tasks**: \`shipbench task list --available --json\`
+- **List blocked tasks**: \`shipbench task list --blocked --json\`
+- **Filter by tags**: \`shipbench task list --available --tag backend,auth --json\`
+- **Read one task**: \`shipbench task get <slug>\`
+- **Search tasks**: \`shipbench task search "<query>" --json\`
+- **Inspect dependencies**: \`shipbench task graph --json\`
+- **Include descriptions in a list**: \`shipbench task list --json --include-body\`
+- **Create a task**: \`shipbench task create "Task title" --status=todo\`
+- **Create a dependent task**: \`shipbench task create "Task title" --depends-on=other-slug,another-slug\`
+- **Add a time-anchored update**: \`shipbench task comment <slug> "What changed and why."\`
+- **Edit an update's text**: \`shipbench task comment edit <slug> <index> "Corrected text."\`
+- **Delete an update**: \`shipbench task comment delete <slug> <index>\`
+- **Move a task**: \`shipbench task move <slug> --to=in-progress\`
+- **Complete a task**: \`shipbench task move <slug> --to=done\`
+- **Reorder a task when explicitly asked**: \`shipbench task move <slug> --before=other-slug\` (also \`--top\`, \`--bottom\`, \`--after\`, \`--position <n>\`)
+- **Archive a task**: \`shipbench task archive <slug>\`
+- **Bulk archive done tasks when explicitly requested**: \`shipbench task archive --done\` (add \`--keep=N\` to retain a specific number)
+- **List archived tasks**: \`shipbench task list --archived\`
+- **Unarchive a task**: \`shipbench task unarchive <slug>\`
+- **Delete a task**: \`shipbench task delete <slug>\`
+- **Open the board**: \`shipbench board\`
+- **Watch the board in the terminal**: \`shipbench board terminal\` (read-only; \`--status\`, \`--tag\`, \`--assignee\`, \`--priority\` narrow it)
+
+### Direct File Operations
+
+Use direct edits only when the CLI is unavailable or when changing task description/frontmatter fields the CLI does not support yet.
+
+- **Create a task**: Add a new \`.md\` file in \`tasks/\` following the format above.
+- **Move a task**: Change the \`status\` field and update the \`updated\` timestamp.
+- **Edit a task**: Modify frontmatter fields and/or the description above \`## Task Updates\`. Always update \`updated\`.
+- **Add an Update without the CLI**: Append a \`### <ISO 8601 timestamp>\` heading and text below the trailing \`## Task Updates\` marker.
+- **Edit an Update without the CLI**: Change only its text; preserve the \`###\` timestamp heading and update the frontmatter \`updated\` value.
+- **Delete an Update without the CLI**: Remove its heading and text, remove an empty \`## Task Updates\` section, and update the frontmatter \`updated\` value.
+- **Delete a task**: Remove the \`.md\` file.
+
+## Important
+
+- Never invent status values not listed in \`config.json\`.
+- Reorder tasks only when the user explicitly asks for it.
+- Always update the \`updated\` timestamp when modifying a task.
+- Do not modify \`config.json\` unless explicitly asked.
+- Do not read \`layout.json\` as the visible order or modify it; the CLI and Board own this partial index.
+- Do not read or modify \`tasks/archive/\` unless the user explicitly asks about archived work.
+- Do not modify the \`created\` timestamp.
+`;
+}
+function generateWelcomeTask(name) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const status = DEFAULT_CONFIG.default_column;
+  const priority = DEFAULT_CONFIG.priority.default;
+  return `---
+title: Welcome to ${name}
+status: ${status}
+priority: ${priority}
+tags: [getting-started]
+created: ${now}
+updated: ${now}
+---
+
+Your ShipBench project board for **${name}** is set up and ready to go.
+
+## Next Steps
+
+- Create new tasks with \`shipbench task create "My first task"\`
+- Open the board with \`shipbench board\`, or watch it in a terminal pane with \`shipbench board terminal\`
+- Edit this file or delete it when you're ready
+`;
+}
+async function initProject(adapter, options) {
+  const initialState = await inspectProjectInitialization(adapter);
+  if (initialState.kind === "initialized") {
+    return {
+      created: false,
+      config: initialState.config,
+      warnings: initialState.warnings
+    };
+  }
+  if (initialState.kind !== "missing") {
+    throw new ProjectInitializationError(initialState);
+  }
+  const { layout: _layout, ...defaultConfig } = DEFAULT_CONFIG;
+  const config = { ...defaultConfig, name: options.name };
+  await adapter.writeFiles(
+    /* @__PURE__ */ new Map([
+      [".shipbench/config.json", `${JSON.stringify(config, null, 2)}
+`],
+      [".shipbench/layout.json", "{}\n"],
+      [".shipbench/README.md", generateReadme(options.name)],
+      [".shipbench/AGENTS.md", generateAgentsMd(options.name)],
+      [
+        ".shipbench/tasks/welcome-to-shipbench.md",
+        generateWelcomeTask(options.name)
+      ]
+    ])
+  );
+  const createdState = await inspectProjectInitialization(adapter);
+  if (createdState.kind !== "initialized") {
+    if (createdState.kind === "missing") {
+      throw new Error("ShipBench initialization did not create config.json.");
+    }
+    throw new ProjectInitializationError(createdState);
+  }
+  return {
+    created: true,
+    config: createdState.config,
+    warnings: createdState.warnings
+  };
+}
+
+// src/search.ts
+var SNIPPET_CONTEXT_BEFORE = 40;
+var SNIPPET_CONTEXT_AFTER = 80;
+function bodySnippet(normalizedBody, normalizedTerms) {
+  const lowercaseBody = normalizedBody.toLowerCase();
+  let matchIndex = -1;
+  let matchLength = 0;
+  for (const term of normalizedTerms) {
+    const termIndex = lowercaseBody.indexOf(term);
+    if (termIndex !== -1 && (matchIndex === -1 || termIndex < matchIndex || termIndex === matchIndex && term.length > matchLength)) {
+      matchIndex = termIndex;
+      matchLength = term.length;
+    }
+  }
+  if (matchIndex === -1) return void 0;
+  const start = Math.max(0, matchIndex - SNIPPET_CONTEXT_BEFORE);
+  const end = Math.min(
+    normalizedBody.length,
+    matchIndex + matchLength + SNIPPET_CONTEXT_AFTER
+  );
+  const excerpt = normalizedBody.slice(start, end).trim();
+  return `${start > 0 ? "\u2026" : ""}${excerpt}${end < normalizedBody.length ? "\u2026" : ""}`;
+}
+function searchTasks(tasks, query) {
+  const normalizedQuery = query.trim().toLowerCase();
+  if (!normalizedQuery) return [];
+  const normalizedTerms = normalizedQuery.split(/\s+/);
+  const matches = [];
+  for (const task of tasks) {
+    const normalizedTitle = task.frontmatter.title.toLowerCase();
+    const normalizedTags = (task.frontmatter.tags ?? []).map(
+      (tag) => tag.toLowerCase()
+    );
+    const normalizedBody = task.body.replace(/\s+/g, " ").trim();
+    const lowercaseBody = normalizedBody.toLowerCase();
+    const everyTermMatches = normalizedTerms.every(
+      (term) => normalizedTitle.includes(term) || normalizedTags.some((tag) => tag.includes(term)) || lowercaseBody.includes(term)
+    );
+    if (!everyTermMatches) continue;
+    const matchedFields = [];
+    if (normalizedTerms.some((term) => normalizedTitle.includes(term))) {
+      matchedFields.push("title");
+    }
+    if (normalizedTerms.some(
+      (term) => normalizedTags.some((tag) => tag.includes(term))
+    )) {
+      matchedFields.push("tags");
+    }
+    const snippet = bodySnippet(normalizedBody, normalizedTerms);
+    if (snippet !== void 0) matchedFields.push("body");
+    matches.push({
+      slug: task.slug,
+      title: task.frontmatter.title,
+      matched_fields: matchedFields,
+      ...snippet !== void 0 ? { snippet } : {}
+    });
+  }
+  return matches;
+}
+export {
+  ArchiveBlockedError,
+  DEFAULT_CONFIG,
+  FsAdapter,
+  GitHubAdapter,
+  GitHubApiError,
+  ProjectInitializationError,
+  addComment,
+  archiveTask,
+  buildTaskDependencyGraph,
+  byCreatedDesc,
+  byUpdatedDesc,
+  createTask,
+  createTaskDependencyIndex,
+  deleteComment,
+  deleteTask,
+  dependencyStatus,
+  editComment,
+  getTask,
+  initProject,
+  inspectProjectInitialization,
+  layoutAfterMove,
+  layoutWithoutTask,
+  listArchivedTasks,
+  listAvailableTasks,
+  listBlockedTasks,
+  listTasks,
+  loadConfig,
+  moveTask,
+  normalizeGithubRemoteUrl,
+  normalizeGithubUrl,
+  orderedTasksForColumn,
+  parseGithubRemoteUrl,
+  parseGithubUrl,
+  reorderTask,
+  resolveSlugCollision,
+  resolveTaskDependency,
+  searchTasks,
+  slugify,
+  taskDependenciesAreSatisfied,
+  taskFileSlugs,
+  unarchiveTask,
+  updateTask,
+  validateConfig
+};