kodi-dev 0.1.1 → 1.0.0

package/dist/index.js

@@ -66,7 +66,9 @@ ${close}`;
   return (base ? base + "\n\n" : "") + block + "\n";
 }
 function installPack(root, packDir, force = false) {
-  const manifest = PackManifestSchema.parse(parseYaml(readFileSync(join(packDir, "manifest.yaml"), "utf-8")));
+  const manifest = PackManifestSchema.parse(
+    parseYaml(readFileSync(join(packDir, "manifest.yaml"), "utf-8"))
+  );
   const skills = copyTree(join(packDir, "skills"), join(root, ".claude", "skills"), force);
   let claudeMdMerged = false;
   if (manifest.claude_md) {
@@ -158,21 +160,252 @@ function registerHookCommand(program2) {
 // src/commands/init.ts
 import {
   copyFileSync as copyFileSync2,
-  existsSync as existsSync3,
-  mkdirSync as mkdirSync2,
+  existsSync as existsSync4,
+  mkdirSync as mkdirSync3,
   readdirSync as readdirSync2,
-  readFileSync as readFileSync3,
+  readFileSync as readFileSync4,
   statSync as statSync2,
-  writeFileSync as writeFileSync2
+  writeFileSync as writeFileSync3
 } from "fs";
-import { dirname as dirname3, join as join3, relative } from "path";
+import { dirname as dirname4, join as join3, relative as relative2 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import { stringify as stringifyYaml } from "yaml";
+import { stringify as stringifyYaml2 } from "yaml";
+
+// src/config.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import { dirname as dirname3, join as join2 } from "path";
+import { parse as parseYaml3 } from "yaml";
+
+// src/providers/status-index.ts
+import {
+  existsSync as existsSync2,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync2,
+  renameSync,
+  unlinkSync,
+  writeFileSync as writeFileSync2
+} from "fs";
+import { randomBytes } from "crypto";
+import { dirname as dirname2, isAbsolute, relative, resolve, sep } from "path";
+import { parse as parseYaml2, stringify as stringifyYaml } from "yaml";
+
+// src/templates/ticket.ts
+import { z as z2 } from "zod";
+var TICKET_STATUSES = ["Pending", "In progress", "To review", "Done"];
+var TicketStatusSchema = z2.enum(TICKET_STATUSES);
+var TicketDriversSchema = z2.object({
+  /** PRD this ticket advances, e.g. "docs/prd/0001". */
+  prd: z2.string().optional(),
+  /** Governing ADR(s), e.g. ["docs/adr/0003"]. */
+  adr: z2.array(z2.string()).default([]),
+  /** Security finding remediated, e.g. "docs/security/AUTH-014". */
+  security: z2.string().optional()
+});
+var TicketSchema = z2.object({
+  key: z2.string().regex(/^[A-Z][A-Z0-9]*-\d+$/, "key must look like PREFIX-123").optional(),
+  title: z2.string().min(3, "title must be at least 3 characters"),
+  slug: z2.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "slug must be kebab-case").optional(),
+  status: TicketStatusSchema.default("Pending"),
+  summary: z2.string().min(1, "summary is required"),
+  acceptanceCriteria: z2.array(z2.string().min(1)).min(1, "at least one acceptance criterion is required"),
+  nonGoals: z2.array(z2.string().min(1)).default([]),
+  /** Ticket keys that must reach Done before this one can start. */
+  dependencies: z2.array(z2.string()).default([]),
+  drivers: TicketDriversSchema.default({}),
+  /** Linked pull request (branch, URL, or id) — set by `link-pr` / `hand-off`. */
+  prUrl: z2.string().optional(),
+  notes: z2.string().optional()
+});
+function slugify(title) {
+  return title.toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60).replace(/-+$/g, "");
+}
+function renderTicketMarkdown(t) {
+  const lines = [];
+  lines.push(`# ${t.key} \u2014 ${t.title}`, "");
+  lines.push(`**Status:** ${t.status}`);
+  if (t.dependencies.length) {
+    lines.push(`**Depends on:** ${t.dependencies.join(", ")}`);
+  }
+  const drivers = [];
+  if (t.drivers.prd) drivers.push(`PRD ${t.drivers.prd}`);
+  if (t.drivers.adr.length) drivers.push(`ADR ${t.drivers.adr.join(", ")}`);
+  if (t.drivers.security) drivers.push(`Security ${t.drivers.security}`);
+  if (drivers.length) lines.push(`**Drivers:** ${drivers.join(" \xB7 ")}`);
+  if (t.prUrl) lines.push(`**PR:** ${t.prUrl}`);
+  lines.push("", "## Summary", "", t.summary, "");
+  lines.push("## Acceptance criteria", "");
+  for (const ac of t.acceptanceCriteria) lines.push(`- [ ] ${ac}`);
+  lines.push("");
+  if (t.nonGoals.length) {
+    lines.push("## Non-goals", "");
+    for (const ng of t.nonGoals) lines.push(`- ${ng}`);
+    lines.push("");
+  }
+  if (t.notes) lines.push("## Notes", "", t.notes, "");
+  return lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+}
+
+// src/providers/status-index.ts
+var SCHEMA_VERSION = 1;
+var STATUS_TO_SLUG = {
+  Pending: "pending",
+  "In progress": "in-progress",
+  "To review": "to-review",
+  Done: "done"
+};
+var SLUG_TO_STATUS = new Map(
+  TICKET_STATUSES.map((status) => [STATUS_TO_SLUG[status], status])
+);
+var KEY_RE = /^[A-Z][A-Z0-9]*-\d+$/;
+var SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var FILE_RE = /^([A-Z][A-Z0-9]*-\d+)-([a-z0-9]+(?:-[a-z0-9]+)*)\.md$/;
+function slugForStatus(status) {
+  const slug = STATUS_TO_SLUG[status];
+  if (slug === void 0) {
+    throw new Error(`unknown ticket status: ${String(status)}`);
+  }
+  return slug;
+}
+function assertKey(key) {
+  if (!KEY_RE.test(key)) {
+    throw new Error(`invalid ticket key ${JSON.stringify(key)}: must match ${KEY_RE.source}`);
+  }
+}
+function assertSlug(slug) {
+  if (!SLUG_RE.test(slug)) {
+    throw new Error(
+      `invalid slug ${JSON.stringify(slug)}: must be strict kebab-case (${SLUG_RE.source})`
+    );
+  }
+}
+function isTicketStatus(value) {
+  return TICKET_STATUSES.includes(value);
+}
+function freshTickets() {
+  return /* @__PURE__ */ Object.create(null);
+}
+function composeFile(status, key, slug) {
+  assertKey(key);
+  assertSlug(slug);
+  return `${slugForStatus(status)}/${key}-${slug}.md`;
+}
+function emptyDocument() {
+  return {
+    version: SCHEMA_VERSION,
+    columns: [...TICKET_STATUSES],
+    tickets: freshTickets()
+  };
+}
+function serialize(doc) {
+  const tickets = {};
+  for (const key of Object.keys(doc.tickets).sort()) {
+    const entry = doc.tickets[key];
+    tickets[key] = { column: entry.column, file: entry.file };
+  }
+  const out2 = {
+    version: doc.version,
+    columns: [...TICKET_STATUSES],
+    tickets
+  };
+  const text = stringifyYaml(out2, { lineWidth: 0 });
+  return text.endsWith("\n") ? text : `${text}
+`;
+}
+function parse(text) {
+  const raw = parseYaml2(text);
+  const tickets = freshTickets();
+  if (raw === null || typeof raw !== "object") {
+    return { version: SCHEMA_VERSION, columns: [...TICKET_STATUSES], tickets };
+  }
+  const obj = raw;
+  const version2 = typeof obj.version === "number" ? obj.version : SCHEMA_VERSION;
+  const rawTickets = obj.tickets;
+  if (rawTickets !== null && typeof rawTickets === "object") {
+    for (const [key, value] of Object.entries(rawTickets)) {
+      if (!KEY_RE.test(key)) continue;
+      if (value === null || typeof value !== "object") continue;
+      const entry = value;
+      const { column, file } = entry;
+      if (typeof column !== "string" || typeof file !== "string") continue;
+      if (!isTicketStatus(column)) continue;
+      tickets[key] = { column, file };
+    }
+  }
+  return { version: version2, columns: [...TICKET_STATUSES], tickets };
+}
+function load(statusYamlPath) {
+  if (!existsSync2(statusYamlPath)) return emptyDocument();
+  return parse(readFileSync2(statusYamlPath, "utf-8"));
+}
+function save(statusYamlPath, doc) {
+  const dir = dirname2(statusYamlPath);
+  mkdirSync2(dir, { recursive: true });
+  const tmp = `${statusYamlPath}.${randomBytes(6).toString("hex")}.tmp`;
+  try {
+    writeFileSync2(tmp, serialize(doc), { encoding: "utf-8", flag: "wx", mode: 384 });
+    renameSync(tmp, statusYamlPath);
+  } catch (err) {
+    try {
+      if (existsSync2(tmp)) unlinkSync(tmp);
+    } catch {
+    }
+    throw err;
+  }
+}
+function assertMutableVersion(doc) {
+  if (doc.version !== SCHEMA_VERSION) {
+    throw new Error(
+      `status.yaml schema version ${doc.version} is unsupported (expected ${SCHEMA_VERSION}); refusing to mutate`
+    );
+  }
+}
+function upsert(doc, input) {
+  assertMutableVersion(doc);
+  const file = composeFile(input.column, input.key, input.slug);
+  doc.tickets[input.key] = { column: input.column, file };
+}
+function remove(doc, key) {
+  assertMutableVersion(doc);
+  delete doc.tickets[key];
+}
+function resolveFile(statusYamlPath, key, entry) {
+  assertKey(key);
+  const file = entry.file;
+  if (file.length === 0 || isAbsolute(file) || file.includes("\\") || // backslash / UNC
+  /^[A-Za-z]:/.test(file)) {
+    throw new Error(`unsafe index file pointer ${JSON.stringify(file)}`);
+  }
+  const segments = file.split("/");
+  if (segments.some((segment) => segment === ".." || segment === "")) {
+    throw new Error(`unsafe index file pointer ${JSON.stringify(file)}`);
+  }
+  if (segments.length !== 2) {
+    throw new Error(`malformed index file pointer ${JSON.stringify(file)}: expected <slug>/<file>`);
+  }
+  const [folder, filename] = segments;
+  const expectedSlug = slugForStatus(entry.column);
+  if (folder !== expectedSlug) {
+    throw new Error(
+      `index/folder disagreement for ${key}: file folder ${JSON.stringify(folder)} != slug(${entry.column})=${JSON.stringify(expectedSlug)}`
+    );
+  }
+  const match = FILE_RE.exec(filename);
+  if (!match || match[1] !== key) {
+    throw new Error(
+      `index key mismatch: file ${JSON.stringify(filename)} does not belong to key ${JSON.stringify(key)}`
+    );
+  }
+  const root = dirname2(statusYamlPath);
+  const resolved = resolve(root, file);
+  const rel = relative(root, resolved);
+  const contained = resolved === root || rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+  if (!contained || !(resolved === root || resolved.startsWith(root + sep))) {
+    throw new Error(`index file pointer escapes tickets root: ${JSON.stringify(file)}`);
+  }
+  return resolved;
+}
 
 // src/config.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
-import { dirname as dirname2, join as join2 } from "path";
-import { parse as parseYaml2 } from "yaml";
 var DEFAULTS = { provider: "local", prefix: "KODI" };
 var STATE_FILE = "kodi-dev.yaml";
 function stateFilePath(root) {
@@ -181,17 +414,17 @@ function stateFilePath(root) {
 function findProjectRoot(cwd = process.cwd()) {
   let dir = cwd;
   while (true) {
-    if (existsSync2(stateFilePath(dir))) return dir;
-    const parent = dirname2(dir);
+    if (existsSync3(stateFilePath(dir))) return dir;
+    const parent = dirname3(dir);
     if (parent === dir) return cwd;
     dir = parent;
   }
 }
 function loadBoardConfig(cwd = process.cwd()) {
   const path = stateFilePath(findProjectRoot(cwd));
-  if (!existsSync2(path)) return { ...DEFAULTS };
+  if (!existsSync3(path)) return { ...DEFAULTS };
   try {
-    const raw = parseYaml2(readFileSync2(path, "utf-8")) ?? {};
+    const raw = parseYaml3(readFileSync3(path, "utf-8")) ?? {};
     return { ...DEFAULTS, ...raw };
   } catch {
     return { ...DEFAULTS };
@@ -201,9 +434,12 @@ function localPaths(cwd = process.cwd()) {
   const root = join2(findProjectRoot(cwd), "docs", "tickets");
   return {
     root,
-    backlog: join2(root, "backlog"),
-    done: join2(root, "done"),
-    index: join2(root, "tickets.md")
+    /** Absolute path to the authoritative `status.yaml` index (data-model §2). */
+    statusYaml: join2(root, "status.yaml"),
+    /** Absolute on-disk folder a ticket in `status` is filed under (data-model §3). */
+    folderFor(status) {
+      return join2(root, slugForStatus(status));
+    }
   };
 }
 
@@ -233,7 +469,13 @@ function execMutate(args, dryRun) {
   if (r.status !== 0) {
     throw new Error(`\`${command}\` failed (exit ${r.status}): ${r.stderr?.trim() || ""}`);
   }
-  return { command, ran: true, stdout: r.stdout ?? "", stderr: r.stderr ?? "", code: r.status ?? 0 };
+  return {
+    command,
+    ran: true,
+    stdout: r.stdout ?? "",
+    stderr: r.stderr ?? "",
+    code: r.status ?? 0
+  };
 }
 
 // src/html.ts
@@ -286,68 +528,6 @@ function mdToHtml(md) {
   return out2.join("\n");
 }
 
-// src/templates/ticket.ts
-import { z as z2 } from "zod";
-var TICKET_STATUSES = [
-  "Pending",
-  "In progress",
-  "To review",
-  "Done",
-  "Blocked"
-];
-var TicketStatusSchema = z2.enum(TICKET_STATUSES);
-var TicketDriversSchema = z2.object({
-  /** PRD this ticket advances, e.g. "docs/prd/0001". */
-  prd: z2.string().optional(),
-  /** Governing ADR(s), e.g. ["docs/adr/0003"]. */
-  adr: z2.array(z2.string()).default([]),
-  /** Security finding remediated, e.g. "docs/security/AUTH-014". */
-  security: z2.string().optional()
-});
-var TicketSchema = z2.object({
-  key: z2.string().regex(/^[A-Z][A-Z0-9]*-\d+$/, "key must look like PREFIX-123").optional(),
-  title: z2.string().min(3, "title must be at least 3 characters"),
-  slug: z2.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "slug must be kebab-case").optional(),
-  status: TicketStatusSchema.default("Pending"),
-  summary: z2.string().min(1, "summary is required"),
-  acceptanceCriteria: z2.array(z2.string().min(1)).min(1, "at least one acceptance criterion is required"),
-  nonGoals: z2.array(z2.string().min(1)).default([]),
-  /** Ticket keys that must reach Done before this one can start. */
-  dependencies: z2.array(z2.string()).default([]),
-  drivers: TicketDriversSchema.default({}),
-  /** Linked pull request (branch, URL, or id) — set by `link-pr` / `hand-off`. */
-  prUrl: z2.string().optional(),
-  notes: z2.string().optional()
-});
-function slugify(title) {
-  return title.toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60).replace(/-+$/g, "");
-}
-function renderTicketMarkdown(t) {
-  const lines = [];
-  lines.push(`# ${t.key} \u2014 ${t.title}`, "");
-  lines.push(`**Status:** ${t.status}`);
-  if (t.dependencies.length) {
-    lines.push(`**Depends on:** ${t.dependencies.join(", ")}`);
-  }
-  const drivers = [];
-  if (t.drivers.prd) drivers.push(`PRD ${t.drivers.prd}`);
-  if (t.drivers.adr.length) drivers.push(`ADR ${t.drivers.adr.join(", ")}`);
-  if (t.drivers.security) drivers.push(`Security ${t.drivers.security}`);
-  if (drivers.length) lines.push(`**Drivers:** ${drivers.join(" \xB7 ")}`);
-  if (t.prUrl) lines.push(`**PR:** ${t.prUrl}`);
-  lines.push("", "## Summary", "", t.summary, "");
-  lines.push("## Acceptance criteria", "");
-  for (const ac of t.acceptanceCriteria) lines.push(`- [ ] ${ac}`);
-  lines.push("");
-  if (t.nonGoals.length) {
-    lines.push("## Non-goals", "");
-    for (const ng of t.nonGoals) lines.push(`- ${ng}`);
-    lines.push("");
-  }
-  if (t.notes) lines.push("## Notes", "", t.notes, "");
-  return lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
-}
-
 // src/providers/azure.ts
 var MARKER_RE = /kodi:ticket:([A-Za-z0-9+/=]+)/;
 var DEFAULT_COLUMNS = {
@@ -394,7 +574,12 @@ function parseWorkItem(fields, id, cols = DEFAULT_COLUMNS) {
   if (!parsed.success) return null;
   const column = fields["System.State"] ?? fields["System.BoardColumn"] ?? "";
   const status = statusFromColumn(column, cols) ?? parsed.data.status;
-  return { ...parsed.data, key: String(id), slug: parsed.data.slug ?? slugify(parsed.data.title), status };
+  return {
+    ...parsed.data,
+    key: String(id),
+    slug: parsed.data.slug ?? slugify(parsed.data.title),
+    status
+  };
 }
 function createArgs(coords, title, html, column) {
   const args = [
@@ -454,13 +639,32 @@ var AzureTicketProvider = class {
     return { ...draft, key: String(id) };
   }
   async get(key) {
-    const out2 = execRead(["az", "boards", "work-item", "show", "--id", key, "--output", "json", ...this.orgArgs()]);
+    const out2 = execRead([
+      "az",
+      "boards",
+      "work-item",
+      "show",
+      "--id",
+      key,
+      "--output",
+      "json",
+      ...this.orgArgs()
+    ]);
     const wi = JSON.parse(out2);
     return parseWorkItem(wi.fields ?? {}, wi.id, this.columns);
   }
   async list() {
     const wiql = "SELECT [System.Id] FROM WorkItems WHERE [System.WorkItemType] = 'Issue' ORDER BY [System.Id]";
-    const out2 = execRead(["az", "boards", "query", "--wiql", wiql, "--output", "json", ...this.scopeArgs()]);
+    const out2 = execRead([
+      "az",
+      "boards",
+      "query",
+      "--wiql",
+      wiql,
+      "--output",
+      "json",
+      ...this.scopeArgs()
+    ]);
     const rows = JSON.parse(out2);
     const refs = [];
     for (const row of rows) {
@@ -488,7 +692,17 @@ var AzureTicketProvider = class {
     const current = await this.get(key);
     if (!current) throw new Error(`work-item ${key} not found`);
     execMutate(
-      ["az", "boards", "work-item", "update", "--id", key, "--fields", `System.State=${columnForStatus(status, this.columns)}`, ...this.orgArgs()],
+      [
+        "az",
+        "boards",
+        "work-item",
+        "update",
+        "--id",
+        key,
+        "--fields",
+        `System.State=${columnForStatus(status, this.columns)}`,
+        ...this.orgArgs()
+      ],
       this.opts.dryRun
     );
     return { ...current, status };
@@ -508,11 +722,20 @@ var AzureTicketProvider = class {
     return merged;
   }
   async delete(key) {
-    execMutate(["az", "boards", "work-item", "delete", "--id", key, "--yes", ...this.scopeArgs()], this.opts.dryRun);
+    execMutate(
+      ["az", "boards", "work-item", "delete", "--id", key, "--yes", ...this.scopeArgs()],
+      this.opts.dryRun
+    );
   }
 };
 function toRef(t) {
-  return { key: t.key, title: t.title, status: t.status, slug: t.slug, dependencies: t.dependencies };
+  return {
+    key: t.key,
+    title: t.title,
+    status: t.status,
+    slug: t.slug,
+    dependencies: t.dependencies
+  };
 }
 
 // src/providers/azure-discovery.ts
@@ -540,7 +763,18 @@ function parseProjectInfo(json) {
 function getProjectInfo(org, project, run = defaultRunner) {
   try {
     return parseProjectInfo(
-      run(["az", "devops", "project", "show", "--project", project, "--org", org, "--output", "json"])
+      run([
+        "az",
+        "devops",
+        "project",
+        "show",
+        "--project",
+        project,
+        "--org",
+        org,
+        "--output",
+        "json"
+      ])
     );
   } catch {
     return null;
@@ -587,7 +821,17 @@ function parseProjects2(json) {
   return items.map((p) => ({ number: p?.number, title: p?.title ?? "", id: p?.id ?? "" })).filter((p) => typeof p.number === "number");
 }
 function listProjects2(owner, run = defaultRunner2) {
-  const out2 = run(["gh", "project", "list", "--owner", owner, "--format", "json", "--limit", "100"]);
+  const out2 = run([
+    "gh",
+    "project",
+    "list",
+    "--owner",
+    owner,
+    "--format",
+    "json",
+    "--limit",
+    "100"
+  ]);
   return parseProjects2(out2);
 }
 function resolveViewerLogin(run = defaultRunner2) {
@@ -628,7 +872,9 @@ function parseStatusField(json) {
     (f) => typeof f?.name === "string" && f.name.toLowerCase() === "status" && Array.isArray(f?.options)
   );
   if (!status) return null;
-  const options = status.options.map((o) => ({ id: o?.id, name: o?.name })).filter((o) => typeof o.id === "string" && typeof o.name === "string");
+  const options = status.options.map((o) => ({ id: o?.id, name: o?.name })).filter(
+    (o) => typeof o.id === "string" && typeof o.name === "string"
+  );
   return { id: status.id, options };
 }
 function listStatusField(owner, number, run = defaultRunner2) {
@@ -670,7 +916,9 @@ function readlinePrompter() {
     async select(message, choices) {
       if (choices.length === 0) throw new Error(`${message}: no choices available`);
       if (!process.stdin.isTTY) {
-        throw new Error(`cannot prompt "${message}" in non-interactive mode \u2014 pass the corresponding flag`);
+        throw new Error(
+          `cannot prompt "${message}" in non-interactive mode \u2014 pass the corresponding flag`
+        );
       }
       return inqSelect({
         message,
@@ -707,17 +955,17 @@ function defaultAssetsDir() {
 }
 function copyTree2(srcRoot, destRoot, force, reportBase) {
   const written = [];
-  if (!existsSync3(srcRoot)) return written;
+  if (!existsSync4(srcRoot)) return written;
   const walk = (src, dest) => {
     for (const entry of readdirSync2(src)) {
       const s = join3(src, entry);
       const d = join3(dest, entry);
       if (statSync2(s).isDirectory()) walk(s, d);
       else {
-        if (existsSync3(d) && !force) continue;
-        mkdirSync2(dirname3(d), { recursive: true });
+        if (existsSync4(d) && !force) continue;
+        mkdirSync3(dirname4(d), { recursive: true });
         copyFileSync2(s, d);
-        written.push(join3(reportBase, relative(destRoot, d)));
+        written.push(join3(reportBase, relative2(destRoot, d)));
       }
     }
   };
@@ -726,15 +974,15 @@ function copyTree2(srcRoot, destRoot, force, reportBase) {
 }
 function copyMarkdownFlat(srcRoot, destDir, force, reportBase) {
   const written = [];
-  if (!existsSync3(srcRoot)) return written;
+  if (!existsSync4(srcRoot)) return written;
   const walk = (dir) => {
     for (const entry of readdirSync2(dir)) {
       const s = join3(dir, entry);
       if (statSync2(s).isDirectory()) walk(s);
       else if (entry.endsWith(".md") && entry !== "README.md") {
         const d = join3(destDir, entry);
-        if (existsSync3(d) && !force) continue;
-        mkdirSync2(destDir, { recursive: true });
+        if (existsSync4(d) && !force) continue;
+        mkdirSync3(destDir, { recursive: true });
         copyFileSync2(s, d);
         written.push(join3(reportBase, entry));
       }
@@ -748,11 +996,11 @@ function installHarness(root, opts = {}) {
   const assetsDir = opts.assetsDir ?? defaultAssetsDir();
   const claude = join3(root, ".claude");
   const changed = [];
-  mkdirSync2(claude, { recursive: true });
+  mkdirSync3(claude, { recursive: true });
   const settingsPath = join3(claude, "settings.json");
-  const settings = existsSync3(settingsPath) ? JSON.parse(readFileSync3(settingsPath, "utf-8")) : {};
+  const settings = existsSync4(settingsPath) ? JSON.parse(readFileSync4(settingsPath, "utf-8")) : {};
   if (mergeSessionStartHook(settings)) {
-    writeFileSync2(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+    writeFileSync3(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
     changed.push(".claude/settings.json (SessionStart hook)");
   }
   changed.push(
@@ -760,8 +1008,11 @@ function installHarness(root, opts = {}) {
     ...copyMarkdownFlat(join3(assetsDir, "agents"), join3(claude, "agents"), force, ".claude/agents"),
     ...copyTree2(join3(assetsDir, "rules"), join3(claude, "rules"), force, ".claude/rules")
   );
-  for (const sub of ["prd", "adr", "diagrams", "plan", "tickets", "security"]) {
-    mkdirSync2(join3(root, "docs", sub), { recursive: true });
+  const provider = opts.provider ?? "local";
+  const docsSubs = ["prd", "adr", "diagrams", "plan", "security"];
+  if (provider === "local") docsSubs.push("tickets");
+  for (const sub of docsSubs) {
+    mkdirSync3(join3(root, "docs", sub), { recursive: true });
   }
   return changed;
 }
@@ -791,7 +1042,9 @@ async function configureBoard(prompter, opts = {}) {
   let project = opts.project;
   if (project) {
     if (!projects.includes(project)) {
-      throw new InitAbort(`project "${project}" not found in ${org} (found: ${projects.join(", ")}).`);
+      throw new InitAbort(
+        `project "${project}" not found in ${org} (found: ${projects.join(", ")}).`
+      );
     }
   } else {
     project = await prompter.select("Select a project", projects);
@@ -827,13 +1080,26 @@ async function configureBoard(prompter, opts = {}) {
   } else if (proposed.length > 0) {
     todo = proposed.length === 1 ? proposed[0] : await prompter.select("To Do column (where new issues are created)", proposed);
   } else {
-    todo = await prompter.input("To Do column (where new issues are created)", DEFAULT_COLUMNS.todo);
+    todo = await prompter.input(
+      "To Do column (where new issues are created)",
+      DEFAULT_COLUMNS.todo
+    );
     if (!todo) throw new InitAbort("missing: the To Do column.");
   }
   const columns = {
     todo,
-    inProgress: await pick(opts.inProgressColumn, "In Progress column", inProg, DEFAULT_COLUMNS.inProgress),
-    toReview: await pick(opts.toReviewColumn, "To Review column", inProg, DEFAULT_COLUMNS.toReview),
+    inProgress: await pick(
+      opts.inProgressColumn,
+      "In Progress column",
+      inProg,
+      DEFAULT_COLUMNS.inProgress
+    ),
+    toReview: await pick(
+      opts.toReviewColumn,
+      "To Review column",
+      inProg,
+      DEFAULT_COLUMNS.toReview
+    ),
     done: await pick(opts.doneColumn, "Done column", completed, DEFAULT_COLUMNS.done)
   };
   const repository = opts.repository ?? (await prompter.input("Repository name for pull requests", project) || project);
@@ -847,7 +1113,10 @@ async function configureGithub(prompter, opts) {
   }
   let owner = opts.projectOwner;
   if (!owner) {
-    const ownerType = opts.ownerType ?? await prompter.select("Is the board owned by an organization or a user?", ["organization", "user"]);
+    const ownerType = opts.ownerType ?? await prompter.select("Is the board owned by an organization or a user?", [
+      "organization",
+      "user"
+    ]);
     if (ownerType === "user") {
       let login = "";
       try {
@@ -890,7 +1159,8 @@ async function configureGithub(prompter, opts) {
     );
   }
   const options = statusField.options.map((o) => o.name);
-  if (options.length === 0) throw new InitAbort(`the Status field on project #${number} has no options.`);
+  if (options.length === 0)
+    throw new InitAbort(`the Status field on project #${number} has no options.`);
   const pick = async (flag, message) => {
     if (flag) return flag;
     return options.length === 1 ? options[0] : prompter.select(message, options);
@@ -914,19 +1184,27 @@ async function configureGithub(prompter, opts) {
     } catch {
     }
     if (repos.length > 0) {
-      if (detected && repos.includes(detected)) repos = [detected, ...repos.filter((r) => r !== detected)];
+      if (detected && repos.includes(detected))
+        repos = [detected, ...repos.filter((r) => r !== detected)];
       repository = await prompter.select("Repository for issues", repos);
     } else {
       repository = await prompter.input("Repository for issues (owner/repo)", detected) || detected;
     }
   }
   if (!repository) throw new InitAbort("missing: repository (owner/repo).");
-  return { provider: "github", prefix: "KODI", repository, projectOwner: owner, projectNumber: number, columns };
+  return {
+    provider: "github",
+    prefix: "KODI",
+    repository,
+    projectOwner: owner,
+    projectNumber: number,
+    columns
+  };
 }
 function writeState(root, config) {
   const path = stateFilePath(root);
-  mkdirSync2(dirname3(path), { recursive: true });
-  writeFileSync2(path, stringifyYaml(config), "utf-8");
+  mkdirSync3(dirname4(path), { recursive: true });
+  writeFileSync3(path, stringifyYaml2(config), "utf-8");
   return path;
 }
 function registerInitCommand(program2) {
@@ -963,13 +1241,13 @@ kodi init aborted \u2014 ${e.message}
     } finally {
       prompter.close();
     }
-    const changed = installHarness(root, { force: o.force });
+    const changed = installHarness(root, { force: o.force, provider: config.provider });
     const statePath = writeState(root, config);
     process.stdout.write(
       `
 kodi init: installed
 ${changed.map((c) => `  + ${c}`).join("\n")}
-  + ${relative(root, statePath)} (provider: ${config.provider})
+  + ${relative2(root, statePath)} (provider: ${config.provider})
 
 SessionStart wired to \`${HOOK_COMMAND}\` (matchers: ${SESSION_MATCHER}).
 `
@@ -978,7 +1256,7 @@ SessionStart wired to \`${HOOK_COMMAND}\` (matchers: ${SESSION_MATCHER}).
 }
 
 // src/commands/pr.ts
-import { mkdtempSync, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
+import { mkdtempSync, readFileSync as readFileSync5, writeFileSync as writeFileSync4 } from "fs";
 import { tmpdir } from "os";
 import { join as join4 } from "path";
 
@@ -1023,7 +1301,7 @@ function resolveTarget(explicit) {
   );
 }
 function draftFromOptions(o) {
-  if (o.file) return PrSchema.parse(JSON.parse(readFileSync4(String(o.file), "utf-8")));
+  if (o.file) return PrSchema.parse(JSON.parse(readFileSync5(String(o.file), "utf-8")));
   return PrSchema.parse({
     title: o.title,
     summary: o.summary,
@@ -1037,7 +1315,19 @@ function draftFromOptions(o) {
   });
 }
 function githubCreateArgs(pr, bodyFile, source, target, repo) {
-  const args = ["gh", "pr", "create", "--title", pr.title, "--body-file", bodyFile, "--base", target, "--head", source];
+  const args = [
+    "gh",
+    "pr",
+    "create",
+    "--title",
+    pr.title,
+    "--body-file",
+    bodyFile,
+    "--base",
+    target,
+    "--head",
+    source
+  ];
   for (const r of pr.reviewers) args.push("--reviewer", r);
   if (repo) args.push("--repo", repo);
   return args;
@@ -1069,7 +1359,7 @@ function registerPrCommand(program2) {
     let args;
     if (target === "github") {
       const bodyFile = join4(mkdtempSync(join4(tmpdir(), "kodi-pr-")), "body.md");
-      writeFileSync3(bodyFile, renderPrMarkdown(draft), "utf-8");
+      writeFileSync4(bodyFile, renderPrMarkdown(draft), "utf-8");
       args = githubCreateArgs(draft, bodyFile, o.source, o.target, repo);
     } else {
       args = azureCreateArgs(draft, renderPrHtml(draft), o.source, o.target, repo);
@@ -1095,47 +1385,561 @@ function collect(value, previous) {
   return previous.concat([value]);
 }
 
-// src/commands/tickets.ts
-import { readFileSync as readFileSync6 } from "fs";
-
-// src/providers/github.ts
-import { mkdtempSync as mkdtempSync2, writeFileSync as writeFileSync4 } from "fs";
-import { tmpdir as tmpdir2 } from "os";
-import { join as join5 } from "path";
-var MARKER_RE2 = /<!--\s*kodi:ticket\s+(\{[\s\S]*?\})\s*-->/;
-var DEFAULT_COLUMNS2 = {
-  todo: "Todo",
-  inProgress: "In Progress",
-  toReview: "In Progress",
-  done: "Done"
-};
-function columnForStatus2(status, cols) {
-  switch (status) {
-    case "In progress":
-      return cols.inProgress ?? DEFAULT_COLUMNS2.inProgress;
-    case "To review":
-      return cols.toReview ?? DEFAULT_COLUMNS2.toReview;
-    case "Done":
-      return cols.done ?? DEFAULT_COLUMNS2.done;
-    default:
-      return cols.todo;
-  }
+// src/commands/serve.ts
+import { spawn } from "child_process";
+import { existsSync as existsSync5 } from "fs";
+import net from "net";
+import { dirname as dirname5, resolve as resolve2 } from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
+var LISTEN_TIMEOUT_MS = 15e3;
+var PROBE_INTERVAL_MS = 200;
+var KILL_GRACE_MS = 2500;
+function resolveBoardServer() {
+  const moduleDir = dirname5(fileURLToPath3(import.meta.url));
+  const candidates = [
+    resolve2(moduleDir, "..", "board-dist", "server.js"),
+    resolve2(moduleDir, "..", "..", "board-dist", "server.js")
+  ];
+  for (const candidate of candidates) {
+    if (existsSync5(candidate)) return candidate;
+  }
+  throw new Error("board not built \u2014 run `pnpm build` before `kodi tickets serve`");
+}
+function pickFreePort() {
+  return new Promise((resolvePort, reject) => {
+    const probe = net.createServer();
+    probe.unref();
+    probe.once("error", reject);
+    probe.listen(0, "127.0.0.1", () => {
+      const addr = probe.address();
+      if (addr && typeof addr === "object") {
+        const { port } = addr;
+        probe.close(() => resolvePort(port));
+      } else {
+        probe.close(() => reject(new Error("could not determine a free port")));
+      }
+    });
+  });
 }
-function statusFromColumn2(column, cols) {
-  if (column === cols.todo) return "Pending";
-  if (column === (cols.inProgress ?? DEFAULT_COLUMNS2.inProgress)) return "In progress";
-  if (column === (cols.toReview ?? DEFAULT_COLUMNS2.toReview)) return "To review";
-  if (column === (cols.done ?? DEFAULT_COLUMNS2.done)) return "Done";
-  return void 0;
+function waitForListen(port, timeoutMs, shouldStop) {
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolveReady, reject) => {
+    const attempt = () => {
+      if (shouldStop()) {
+        reject(new Error("aborted: board exited before it started listening"));
+        return;
+      }
+      const socket = net.connect({ host: "127.0.0.1", port });
+      socket.once("connect", () => {
+        socket.destroy();
+        resolveReady();
+      });
+      socket.once("error", () => {
+        socket.destroy();
+        if (Date.now() >= deadline) {
+          reject(new Error("board server did not start listening within timeout"));
+          return;
+        }
+        const timer = setTimeout(attempt, PROBE_INTERVAL_MS);
+        timer.unref();
+      });
+    };
+    attempt();
+  });
 }
-function serializeBody(t) {
-  const canonical = JSON.stringify({ ...t, key: void 0 });
-  return `${renderTicketMarkdown(t)}
-<!-- kodi:ticket ${canonical} -->
-`;
+function openBrowser(url) {
+  let child;
+  try {
+    if (process.platform === "darwin") {
+      child = spawn("open", [url], { stdio: "ignore" });
+    } else if (process.platform === "win32") {
+      child = spawn("cmd", ["/c", "start", "", url], { stdio: "ignore" });
+    } else {
+      child = spawn("xdg-open", [url], { stdio: "ignore" });
+    }
+    child.once("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
 }
-function parseMarker(body) {
-  const m = body ? MARKER_RE2.exec(body) : null;
+function buildBoardEnv(port, ticketsDir) {
+  const env = {
+    // Minimal base so node can locate itself and its user dirs.
+    PATH: process.env.PATH,
+    HOME: process.env.HOME,
+    // Loopback ONLY. The standalone server binds HOSTNAME (default 0.0.0.0), so
+    // this literal is what actually keeps the board off the network. HOST is set
+    // too for good measure — HOSTNAME alone is what Next standalone honors.
+    HOSTNAME: "127.0.0.1",
+    HOST: "127.0.0.1",
+    PORT: String(port),
+    KODI_TICKETS_DIR: ticketsDir,
+    NODE_ENV: "production"
+  };
+  if (process.platform === "win32") {
+    if (process.env.SystemRoot) env.SystemRoot = process.env.SystemRoot;
+    if (process.env.APPDATA) env.APPDATA = process.env.APPDATA;
+  }
+  return env;
+}
+function parsePortOption(raw) {
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 1 || n > 65535) {
+    throw new Error(`invalid --port "${raw}" (expected an integer 1..65535)`);
+  }
+  return n;
+}
+function registerServeCommand(program2) {
+  const tickets = program2.commands.find((c) => c.name() === "tickets");
+  if (!tickets) {
+    throw new Error("internal: `tickets` command must be registered before `serve`");
+  }
+  tickets.command("serve").alias("open").description("Launch the local board UI in the browser (read-only view of docs/tickets)").option("--port <n>", "bind the board to a specific port (default: an OS-picked free port)").action(async (o) => {
+    const ticketsDir = resolve2(localPaths(process.cwd()).root);
+    let serverJs;
+    try {
+      serverJs = resolveBoardServer();
+    } catch (err) {
+      process.stderr.write(`${err instanceof Error ? err.message : String(err)}
+`);
+      process.exitCode = 1;
+      return;
+    }
+    const port = o.port !== void 0 ? parsePortOption(String(o.port)) : await pickFreePort();
+    const env = buildBoardEnv(port, ticketsDir);
+    const child = spawn(process.execPath, [serverJs], {
+      env,
+      stdio: ["ignore", "ignore", "inherit"]
+    });
+    await new Promise((resolveAction) => {
+      let settled = false;
+      let shuttingDown = false;
+      let overrideCode = null;
+      let forceTimer;
+      const detachSignals = () => {
+        process.off("SIGINT", onSignal);
+        process.off("SIGTERM", onSignal);
+        process.off("exit", onProcessExit);
+      };
+      const finish = (code) => {
+        if (settled) return;
+        settled = true;
+        if (forceTimer) clearTimeout(forceTimer);
+        detachSignals();
+        process.exitCode = code;
+        resolveAction();
+      };
+      const shutdown = (code) => {
+        if (code !== void 0) overrideCode = code;
+        if (shuttingDown) return;
+        shuttingDown = true;
+        if (child.exitCode === null && child.signalCode === null) {
+          child.kill("SIGTERM");
+          forceTimer = setTimeout(() => {
+            child.kill("SIGKILL");
+          }, KILL_GRACE_MS);
+          forceTimer.unref();
+        } else {
+          finish(overrideCode ?? 0);
+        }
+      };
+      const onSignal = () => shutdown();
+      const onProcessExit = () => {
+        if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+      };
+      process.on("SIGINT", onSignal);
+      process.on("SIGTERM", onSignal);
+      process.on("exit", onProcessExit);
+      child.on("error", (err) => {
+        process.stderr.write(`failed to start board server: ${err.message}
+`);
+        finish(1);
+      });
+      child.on("exit", (code, signal) => {
+        const resolved = overrideCode ?? (code == null ? signal ? 0 : 1 : code);
+        finish(resolved);
+      });
+      waitForListen(port, LISTEN_TIMEOUT_MS, () => settled).then(() => {
+        if (settled) return;
+        const url = `http://127.0.0.1:${port}`;
+        process.stdout.write(`Board running at ${url}. To stop the server, press Ctrl+C.
+`);
+        if (process.env.KODI_NO_OPEN) {
+          process.stdout.write("KODI_NO_OPEN set \u2014 not opening a browser.\n");
+          return;
+        }
+        openBrowser(url);
+      }).catch(() => {
+        if (settled) return;
+        process.stderr.write("board server did not become ready \u2014 shutting down.\n");
+        shutdown(1);
+      });
+    });
+  });
+}
+
+// src/commands/tickets.ts
+import { readFileSync as readFileSync7 } from "fs";
+
+// src/providers/local.ts
+import { randomBytes as randomBytes2 } from "crypto";
+import {
+  existsSync as existsSync6,
+  lstatSync,
+  mkdirSync as mkdirSync4,
+  readdirSync as readdirSync3,
+  readFileSync as readFileSync6,
+  renameSync as renameSync2,
+  unlinkSync as unlinkSync2,
+  writeFileSync as writeFileSync5
+} from "fs";
+import { basename as basename2, join as join5 } from "path";
+import { parse as parseYaml4, stringify as stringifyYaml3 } from "yaml";
+var FRONTMATTER = /^---\n([\s\S]*?)\n---\n?/;
+var LEGACY_FOLDERS = ["backlog", "done"];
+var LEGACY_FILENAME_RE = /^[A-Z][A-Z0-9]*-\d+-.*\.md$/;
+var LegacyDataError = class extends Error {
+  report;
+  constructor(folders, ticketCount) {
+    super(
+      `legacy ticket data present under docs/tickets/{${folders.join(", ")}} (${ticketCount} ticket-shaped file(s)); clean-start refuses to migrate`
+    );
+    this.name = "LegacyDataError";
+    this.report = { ok: false, reason: "legacy-data-present", folders: [...folders], ticketCount };
+  }
+};
+var LocalTicketProvider = class {
+  name = "local";
+  prefix;
+  paths;
+  constructor(prefix, cwd = process.cwd()) {
+    this.prefix = prefix;
+    this.paths = localPaths(cwd);
+  }
+  /**
+   * Lazy idempotent scaffold (R-003, ADR-0001 §2.3): ensure `status.yaml` and
+   * the four status folders exist. A valid pre-existing `status.yaml`
+   * short-circuits the fresh-index write, so re-running never duplicates or
+   * corrupts an existing index. `mkdirSync({recursive:true})` is itself
+   * idempotent for the folders.
+   */
+  scaffold() {
+    this.detectLegacyData();
+    if (!existsSync6(this.paths.statusYaml)) {
+      save(this.paths.statusYaml, emptyDocument());
+    }
+    for (const status of TICKET_STATUSES) {
+      mkdirSync4(this.paths.folderFor(status), { recursive: true });
+    }
+  }
+  /**
+   * Evaluate the data-model §5 legacy predicate and throw {@link LegacyDataError}
+   * when it holds — non-destructively, before any scaffold write:
+   *
+   *   legacyPresent := !exists(status.yaml)
+   *     AND (exists(backlog/) OR exists(done/))
+   *     AND countTicketShapedMd(backlog/, done/) >= 1
+   *
+   * Security posture (guidance pass): zero writes on this path (SR-A); FAILS SAFE
+   * — any error while *determining* presence aborts-and-reports rather than
+   * falling through to scaffold writes (SR-B); a per-file parse/read failure is a
+   * legitimate "not ticket-shaped" and never crashes (SR-C). It short-circuits at
+   * the first confirmed ticket-shaped file (SR-H).
+   */
+  detectLegacyData() {
+    if (existsSync6(this.paths.statusYaml)) return;
+    const states = LEGACY_FOLDERS.map((name2) => ({ name: name2, state: this.legacyDirState(name2) }));
+    const present = states.filter((s) => s.state !== "absent");
+    if (present.length === 0) return;
+    const folders = present.map((s) => s.name);
+    if (present.some((s) => s.state === "unsafe")) {
+      throw new LegacyDataError(folders, 1);
+    }
+    for (const { name: name2, state } of states) {
+      if (state !== "dir") continue;
+      const dir = join5(this.paths.root, name2);
+      let entries;
+      try {
+        entries = readdirSync3(dir, { withFileTypes: true });
+      } catch {
+        throw new LegacyDataError(folders, 1);
+      }
+      for (const dirent of entries) {
+        if (!dirent.isFile()) continue;
+        if (!LEGACY_FILENAME_RE.test(dirent.name)) continue;
+        if (legacyFileHasKey(join5(dir, dirent.name))) {
+          throw new LegacyDataError(folders, 1);
+        }
+      }
+    }
+  }
+  /**
+   * Classify a candidate legacy folder without following symlinks (SR-E). Uses
+   * `lstat` so a symlinked `backlog/`/`done/` is flagged `unsafe` (never followed
+   * out of tree); a missing folder is `absent`; a stat/permission failure is
+   * `unsafe` (SR-B fail-safe); a real directory is `dir`.
+   */
+  legacyDirState(name2) {
+    const dir = join5(this.paths.root, name2);
+    let st;
+    try {
+      st = lstatSync(dir);
+    } catch (err) {
+      if (err.code === "ENOENT") return "absent";
+      return "unsafe";
+    }
+    if (st.isSymbolicLink()) return "unsafe";
+    if (!st.isDirectory()) return "absent";
+    return "dir";
+  }
+  parseFile(path) {
+    let raw;
+    try {
+      raw = readFileSync6(path, "utf-8");
+    } catch {
+      return null;
+    }
+    const m = FRONTMATTER.exec(raw);
+    if (!m) return null;
+    const meta = parseYaml4(m[1]) ?? {};
+    const parsed = TicketSchema.safeParse(meta);
+    if (!parsed.success || !parsed.data.key || !parsed.data.slug) return null;
+    return parsed.data;
+  }
+  /**
+   * Resolve a ticket through the index (index-wins). Returns the absolute file
+   * path, the index entry (authoritative column), and the parsed ticket, or
+   * null when the key is not indexed / the pointer does not resolve.
+   */
+  locate(key) {
+    const doc = load(this.paths.statusYaml);
+    const entry = doc.tickets[key];
+    if (!entry) return null;
+    let path;
+    try {
+      path = resolveFile(this.paths.statusYaml, key, entry);
+    } catch {
+      return null;
+    }
+    const ticket = this.parseFile(path);
+    if (!ticket) return null;
+    return { path, entry, ticket };
+  }
+  /**
+   * Write a ticket markdown file for its `ticket.status` column: render the body
+   * (frontmatter `status` mirrors the column) and land it via a random-suffixed,
+   * exclusively-opened temp file IN THE SAME target folder, then an intra-folder
+   * atomic rename over the final `<KEY>-<slug>.md` (ADR-0001 §2.4; SR-4/SR-5).
+   * Returns the final absolute path. `sortTicket()` output is byte-identical to
+   * the previous model (R-005).
+   */
+  writeTicketFile(ticket) {
+    const dir = this.paths.folderFor(ticket.status);
+    mkdirSync4(dir, { recursive: true });
+    const finalName = basename2(composeFile(ticket.status, ticket.key, ticket.slug));
+    const finalPath = join5(dir, finalName);
+    const body = `---
+${stringifyYaml3(sortTicket(ticket)).trimEnd()}
+---
+
+` + renderTicketMarkdown(ticket);
+    const tmp = join5(dir, `.${finalName}.${randomBytes2(6).toString("hex")}.tmp`);
+    try {
+      writeFileSync5(tmp, body, { encoding: "utf-8", flag: "wx", mode: 384 });
+      renameSync2(tmp, finalPath);
+    } catch (err) {
+      try {
+        if (existsSync6(tmp)) unlinkSync2(tmp);
+      } catch {
+      }
+      throw err;
+    }
+    return finalPath;
+  }
+  /** Index-driven enumeration: one ref per `status.yaml` entry, column-authoritative. */
+  collectRefs() {
+    const doc = load(this.paths.statusYaml);
+    const refs = [];
+    for (const [key, entry] of Object.entries(doc.tickets)) {
+      let path;
+      try {
+        path = resolveFile(this.paths.statusYaml, key, entry);
+      } catch {
+        continue;
+      }
+      const t = this.parseFile(path);
+      if (t) refs.push(toRef2({ ...t, status: entry.column }));
+    }
+    return refs.sort((a, b) => a.key.localeCompare(b.key, void 0, { numeric: true }));
+  }
+  async nextId(prefix = this.prefix) {
+    const doc = load(this.paths.statusYaml);
+    let max = 0;
+    for (const key of Object.keys(doc.tickets)) {
+      const m = /^([A-Z][A-Z0-9]*)-(\d+)$/.exec(key);
+      if (m && m[1] === prefix) max = Math.max(max, Number(m[2]));
+    }
+    return `${prefix}-${String(max + 1).padStart(3, "0")}`;
+  }
+  async create(input) {
+    this.scaffold();
+    const key = input.key ?? await this.nextId(this.prefix);
+    if (load(this.paths.statusYaml).tickets[key]) {
+      throw new Error(`ticket ${key} already exists`);
+    }
+    const slug = input.slug ?? slugify(input.title);
+    const ticket = { ...input, key, slug };
+    this.writeTicketFile(ticket);
+    const doc = load(this.paths.statusYaml);
+    upsert(doc, { key, column: ticket.status, slug });
+    save(this.paths.statusYaml, doc);
+    return ticket;
+  }
+  async get(key) {
+    const found = this.locate(key);
+    if (!found) return null;
+    return { ...found.ticket, status: found.entry.column };
+  }
+  async list() {
+    return this.collectRefs();
+  }
+  async listReady() {
+    const all = await this.list();
+    const doneKeys = new Set(all.filter((t) => t.status === "Done").map((t) => t.key));
+    const ready = [];
+    const blocked = [];
+    for (const t of all) {
+      if (t.status !== "Pending") continue;
+      const unmet = t.dependencies.filter((d) => !doneKeys.has(d));
+      if (unmet.length === 0) ready.push(t);
+      else blocked.push({ ticket: t, blockedBy: unmet });
+    }
+    return { ready, blocked };
+  }
+  async setStatus(key, status) {
+    const found = this.locate(key);
+    if (!found) throw new Error(`ticket ${key} not found`);
+    const oldPath = found.path;
+    const ticket = { ...found.ticket, status };
+    const newPath = this.writeTicketFile(ticket);
+    const doc = load(this.paths.statusYaml);
+    upsert(doc, { key, column: status, slug: ticket.slug });
+    save(this.paths.statusYaml, doc);
+    if (oldPath !== newPath) unlinkSync2(oldPath);
+    return ticket;
+  }
+  async start(key, _provenance) {
+    return this.setStatus(key, "In progress");
+  }
+  async amend(key, patch) {
+    const found = this.locate(key);
+    if (!found) throw new Error(`ticket ${key} not found`);
+    const column = found.entry.column;
+    const ticket = {
+      ...found.ticket,
+      ...patch,
+      key,
+      slug: found.ticket.slug,
+      status: column
+    };
+    this.writeTicketFile(ticket);
+    const doc = load(this.paths.statusYaml);
+    upsert(doc, { key, column, slug: ticket.slug });
+    save(this.paths.statusYaml, doc);
+    return ticket;
+  }
+  async delete(key) {
+    const found = this.locate(key);
+    if (!found) throw new Error(`ticket ${key} not found`);
+    const doc = load(this.paths.statusYaml);
+    remove(doc, key);
+    save(this.paths.statusYaml, doc);
+    unlinkSync2(found.path);
+  }
+};
+function legacyFileHasKey(path) {
+  let raw;
+  try {
+    raw = readFileSync6(path, "utf-8");
+  } catch {
+    return false;
+  }
+  const m = FRONTMATTER.exec(raw);
+  if (!m) return false;
+  let meta;
+  try {
+    meta = parseYaml4(m[1]);
+  } catch {
+    return false;
+  }
+  if (meta === null || typeof meta !== "object") return false;
+  const key = meta.key;
+  return typeof key === "string" && KEY_RE.test(key);
+}
+function toRef2(t) {
+  return {
+    key: t.key,
+    title: t.title,
+    status: t.status,
+    slug: t.slug,
+    dependencies: t.dependencies
+  };
+}
+function sortTicket(t) {
+  return {
+    key: t.key,
+    title: t.title,
+    slug: t.slug,
+    status: t.status,
+    dependencies: t.dependencies,
+    drivers: t.drivers,
+    summary: t.summary,
+    acceptanceCriteria: t.acceptanceCriteria,
+    nonGoals: t.nonGoals,
+    ...t.prUrl ? { prUrl: t.prUrl } : {},
+    ...t.notes ? { notes: t.notes } : {}
+  };
+}
+
+// src/providers/github.ts
+import { mkdtempSync as mkdtempSync2, writeFileSync as writeFileSync6 } from "fs";
+import { tmpdir as tmpdir2 } from "os";
+import { join as join6 } from "path";
+var MARKER_RE2 = /<!--\s*kodi:ticket\s+(\{[\s\S]*?\})\s*-->/;
+var DEFAULT_COLUMNS2 = {
+  todo: "Todo",
+  inProgress: "In Progress",
+  toReview: "In Progress",
+  done: "Done"
+};
+function columnForStatus2(status, cols) {
+  switch (status) {
+    case "In progress":
+      return cols.inProgress ?? DEFAULT_COLUMNS2.inProgress;
+    case "To review":
+      return cols.toReview ?? DEFAULT_COLUMNS2.toReview;
+    case "Done":
+      return cols.done ?? DEFAULT_COLUMNS2.done;
+    default:
+      return cols.todo;
+  }
+}
+function statusFromColumn2(column, cols) {
+  if (column === cols.todo) return "Pending";
+  if (column === (cols.inProgress ?? DEFAULT_COLUMNS2.inProgress)) return "In progress";
+  if (column === (cols.toReview ?? DEFAULT_COLUMNS2.toReview)) return "To review";
+  if (column === (cols.done ?? DEFAULT_COLUMNS2.done)) return "Done";
+  return void 0;
+}
+function serializeBody(t) {
+  const canonical = JSON.stringify({ ...t, key: void 0 });
+  return `${renderTicketMarkdown(t)}
+<!-- kodi:ticket ${canonical} -->
+`;
+}
+function parseMarker(body) {
+  const m = body ? MARKER_RE2.exec(body) : null;
   if (!m) return null;
   const parsed = TicketSchema.safeParse(JSON.parse(m[1]));
   return parsed.success ? parsed.data : null;
@@ -1146,7 +1950,8 @@ function parseItems(json) {
   const out2 = [];
   for (const it of items) {
     const content = it?.content ?? {};
-    if (content.type !== "Issue" || typeof content.number !== "number" || typeof it?.id !== "string") continue;
+    if (content.type !== "Issue" || typeof content.number !== "number" || typeof it?.id !== "string")
+      continue;
     out2.push({
       itemId: it.id,
       issueNumber: content.number,
@@ -1162,7 +1967,18 @@ function createIssueArgs(repo, title, bodyFile) {
   return args;
 }
 function itemAddArgs(owner, number, issueUrl) {
-  return ["gh", "project", "item-add", String(number), "--owner", owner, "--url", issueUrl, "--format", "json"];
+  return [
+    "gh",
+    "project",
+    "item-add",
+    String(number),
+    "--owner",
+    owner,
+    "--url",
+    issueUrl,
+    "--format",
+    "json"
+  ];
 }
 function itemEditArgs(projectId, itemId, fieldId, optionId) {
   return [
@@ -1216,7 +2032,17 @@ var GithubTicketProvider = class {
   /** Body for an item — from item-list when present, else a per-issue fallback fetch. */
   bodyFor(item) {
     if (item.body != null) return item.body;
-    return execRead(["gh", "issue", "view", String(item.issueNumber), "--json", "body", "-q", ".body", ...this.repoArgs()]);
+    return execRead([
+      "gh",
+      "issue",
+      "view",
+      String(item.issueNumber),
+      "--json",
+      "body",
+      "-q",
+      ".body",
+      ...this.repoArgs()
+    ]);
   }
   toStored(item) {
     const t = parseMarker(this.bodyFor(item));
@@ -1235,7 +2061,10 @@ var GithubTicketProvider = class {
     const r1 = execMutate(createIssueArgs(this.opts.repo, input.title, bodyFile), this.opts.dryRun);
     if (!r1.ran) {
       execMutate(itemAddArgs(this.opts.owner, this.opts.number, "<issue-url>"), this.opts.dryRun);
-      execMutate(itemEditArgs("<project-id>", "<item-id>", "<status-field-id>", "<option-id>"), this.opts.dryRun);
+      execMutate(
+        itemEditArgs("<project-id>", "<item-id>", "<status-field-id>", "<option-id>"),
+        this.opts.dryRun
+      );
       return { ...draft, key: "(dry-run)" };
     }
     const url = r1.stdout.trim().split("\n").pop() ?? "";
@@ -1245,7 +2074,8 @@ var GithubTicketProvider = class {
       const itemId = JSON.parse(add.stdout).id;
       const meta = this.projectMeta();
       const optionId = optionIdFor(meta.statusField, columnForStatus2(input.status, this.columns));
-      if (optionId) execMutate(itemEditArgs(meta.projectId, itemId, meta.statusField.id, optionId), false);
+      if (optionId)
+        execMutate(itemEditArgs(meta.projectId, itemId, meta.statusField.id, optionId), false);
     } catch (e) {
       throw new Error(
         `issue #${num} was created (${url}) but could not be added to project #${this.opts.number}: ${e instanceof Error ? e.message : String(e)}
@@ -1260,7 +2090,7 @@ If your gh token lacks the \`project\` scope, run \`gh auth refresh -s project -
     return item ? this.toStored(item) : null;
   }
   async list() {
-    return this.items().map((i) => this.toStored(i)).filter((t) => t !== null).map(toRef2);
+    return this.items().map((i) => this.toStored(i)).filter((t) => t !== null).map(toRef3);
   }
   async listReady() {
     const all = await this.list();
@@ -1282,8 +2112,12 @@ If your gh token lacks the \`project\` scope, run \`gh auth refresh -s project -
     if (!current) throw new Error(`issue ${key} has no kodi marker`);
     const meta = this.projectMeta();
     const optionId = optionIdFor(meta.statusField, columnForStatus2(status, this.columns));
-    if (!optionId) throw new Error(`no Status option maps to "${status}" on project #${this.opts.number}`);
-    execMutate(itemEditArgs(meta.projectId, item.itemId, meta.statusField.id, optionId), this.opts.dryRun);
+    if (!optionId)
+      throw new Error(`no Status option maps to "${status}" on project #${this.opts.number}`);
+    execMutate(
+      itemEditArgs(meta.projectId, item.itemId, meta.statusField.id, optionId),
+      this.opts.dryRun
+    );
     return { ...current, status };
   }
   async start(key, _p) {
@@ -1303,183 +2137,20 @@ If your gh token lacks the \`project\` scope, run \`gh auth refresh -s project -
     execMutate(["gh", "issue", "delete", key, "--yes", ...this.repoArgs()], this.opts.dryRun);
   }
 };
-function toRef2(t) {
-  return { key: t.key, title: t.title, status: t.status, slug: t.slug, dependencies: t.dependencies };
-}
-function writeTempBody(body) {
-  const file = join5(mkdtempSync2(join5(tmpdir2(), "kodi-gh-")), "body.md");
-  writeFileSync4(file, body, "utf-8");
-  return file;
-}
-
-// src/providers/local.ts
-import {
-  existsSync as existsSync4,
-  mkdirSync as mkdirSync3,
-  readdirSync as readdirSync3,
-  readFileSync as readFileSync5,
-  rmSync,
-  writeFileSync as writeFileSync5
-} from "fs";
-import { join as join6 } from "path";
-import { parse as parseYaml3, stringify as stringifyYaml2 } from "yaml";
-var FRONTMATTER = /^---\n([\s\S]*?)\n---\n?/;
-var LocalTicketProvider = class {
-  name = "local";
-  prefix;
-  paths;
-  constructor(prefix, cwd = process.cwd()) {
-    this.prefix = prefix;
-    this.paths = localPaths(cwd);
-  }
-  ensureDirs() {
-    mkdirSync3(this.paths.backlog, { recursive: true });
-    mkdirSync3(this.paths.done, { recursive: true });
-  }
-  fileName(t) {
-    return `${t.key}-${t.slug}.md`;
-  }
-  /** Directory a ticket file lives in for a given status. */
-  dirFor(status) {
-    return status === "Done" ? this.paths.done : this.paths.backlog;
-  }
-  allFiles() {
-    const out2 = [];
-    for (const dir of [this.paths.backlog, this.paths.done]) {
-      if (!existsSync4(dir)) continue;
-      for (const file of readdirSync3(dir)) {
-        if (file.endsWith(".md")) out2.push({ dir, file });
-      }
-    }
-    return out2;
-  }
-  parseFile(dir, file) {
-    const raw = readFileSync5(join6(dir, file), "utf-8");
-    const m = FRONTMATTER.exec(raw);
-    if (!m) return null;
-    const meta = parseYaml3(m[1]) ?? {};
-    const parsed = TicketSchema.safeParse(meta);
-    if (!parsed.success || !parsed.data.key || !parsed.data.slug) return null;
-    return parsed.data;
-  }
-  locate(key) {
-    for (const { dir, file } of this.allFiles()) {
-      const ticket = this.parseFile(dir, file);
-      if (ticket && ticket.key === key) return { dir, file, ticket };
-    }
-    return null;
-  }
-  persist(ticket) {
-    this.ensureDirs();
-    const existing = this.locate(ticket.key);
-    if (existing) rmSync(join6(existing.dir, existing.file));
-    const dir = this.dirFor(ticket.status);
-    const body = `---
-${stringifyYaml2(sortTicket(ticket)).trimEnd()}
----
-
-` + renderTicketMarkdown(ticket);
-    writeFileSync5(join6(dir, this.fileName(ticket)), body, "utf-8");
-    this.writeIndex();
-  }
-  async nextId(prefix = this.prefix) {
-    let max = 0;
-    for (const { dir, file } of this.allFiles()) {
-      const t = this.parseFile(dir, file);
-      if (!t) continue;
-      const m = /^([A-Z][A-Z0-9]*)-(\d+)$/.exec(t.key);
-      if (m && m[1] === prefix) max = Math.max(max, Number(m[2]));
-    }
-    return `${prefix}-${String(max + 1).padStart(3, "0")}`;
-  }
-  async create(input) {
-    const key = input.key ?? await this.nextId(this.prefix);
-    if (this.locate(key)) throw new Error(`ticket ${key} already exists`);
-    const slug = input.slug ?? slugify(input.title);
-    const ticket = { ...input, key, slug };
-    this.persist(ticket);
-    return ticket;
-  }
-  async get(key) {
-    return this.locate(key)?.ticket ?? null;
-  }
-  async list() {
-    const refs = [];
-    for (const { dir, file } of this.allFiles()) {
-      const t = this.parseFile(dir, file);
-      if (t) refs.push(toRef3(t));
-    }
-    return refs.sort((a, b) => a.key.localeCompare(b.key, void 0, { numeric: true }));
-  }
-  async listReady() {
-    const all = await this.list();
-    const doneKeys = new Set(all.filter((t) => t.status === "Done").map((t) => t.key));
-    const ready = [];
-    const blocked = [];
-    for (const t of all) {
-      if (t.status !== "Pending") continue;
-      const unmet = t.dependencies.filter((d) => !doneKeys.has(d));
-      if (unmet.length === 0) ready.push(t);
-      else blocked.push({ ticket: t, blockedBy: unmet });
-    }
-    return { ready, blocked };
-  }
-  async setStatus(key, status) {
-    const found = this.locate(key);
-    if (!found) throw new Error(`ticket ${key} not found`);
-    const ticket = { ...found.ticket, status };
-    this.persist(ticket);
-    return ticket;
-  }
-  async start(key, _provenance) {
-    return this.setStatus(key, "In progress");
-  }
-  async amend(key, patch) {
-    const found = this.locate(key);
-    if (!found) throw new Error(`ticket ${key} not found`);
-    const ticket = { ...found.ticket, ...patch, key, slug: found.ticket.slug };
-    this.persist(ticket);
-    return ticket;
-  }
-  async delete(key) {
-    const found = this.locate(key);
-    if (!found) throw new Error(`ticket ${key} not found`);
-    rmSync(join6(found.dir, found.file));
-    this.writeIndex();
-  }
-  writeIndex() {
-    const refs = [];
-    for (const { dir, file } of this.allFiles()) {
-      const t = this.parseFile(dir, file);
-      if (t) refs.push(toRef3(t));
-    }
-    refs.sort((a, b) => a.key.localeCompare(b.key, void 0, { numeric: true }));
-    const lines = ["# Tickets", "", "| Key | Title | Status | Depends on |", "|---|---|---|---|"];
-    for (const t of refs) {
-      lines.push(`| ${t.key} | ${t.title} | ${t.status} | ${t.dependencies.join(", ") || "\u2014"} |`);
-    }
-    lines.push("");
-    writeFileSync5(this.paths.index, lines.join("\n"), "utf-8");
-  }
-};
 function toRef3(t) {
-  return { key: t.key, title: t.title, status: t.status, slug: t.slug, dependencies: t.dependencies };
-}
-function sortTicket(t) {
   return {
     key: t.key,
     title: t.title,
-    slug: t.slug,
     status: t.status,
-    dependencies: t.dependencies,
-    drivers: t.drivers,
-    summary: t.summary,
-    acceptanceCriteria: t.acceptanceCriteria,
-    nonGoals: t.nonGoals,
-    ...t.prUrl ? { prUrl: t.prUrl } : {},
-    ...t.notes ? { notes: t.notes } : {}
+    slug: t.slug,
+    dependencies: t.dependencies
   };
 }
+function writeTempBody(body) {
+  const file = join6(mkdtempSync2(join6(tmpdir2(), "kodi-gh-")), "body.md");
+  writeFileSync6(file, body, "utf-8");
+  return file;
+}
 
 // src/providers/index.ts
 function resolveProvider(cwd = process.cwd(), opts = {}) {
@@ -1516,7 +2187,7 @@ function out(data, json, human) {
 }
 function draftFromOptions2(o) {
   if (o.file) {
-    const raw = JSON.parse(readFileSync6(String(o.file), "utf-8"));
+    const raw = JSON.parse(readFileSync7(String(o.file), "utf-8"));
     return TicketSchema.parse(raw);
   }
   return TicketSchema.parse({
@@ -1537,8 +2208,17 @@ function registerTicketsCommand(program2) {
   const tickets = program2.command("tickets").description("Manage tickets across the active provider (local / github / azure)");
   tickets.command("create").description("Create a ticket (validates the template)").option("-f, --file <path>", "JSON draft file (validated against the ticket template)").option("-t, --title <title>").option("-s, --summary <summary>").option("--ac <criterion>", "acceptance criterion (repeatable)", collect2, []).option("--non-goal <text>", "non-goal (repeatable)", collect2, []).option("--dep <key>", "dependency ticket key (repeatable)", collect2, []).option("--prd <ref>", "PRD driver").option("--adr <ref>", "ADR driver (repeatable)", collect2, []).option("--security <ref>", "security driver").option("--notes <text>").option("--yes", "execute remote mutations (default: dry-run)", false).option("--json", "machine-readable output", false).action(async (o) => {
     const draft = draftFromOptions2(o);
-    const created = await resolveProvider(process.cwd(), { yes: o.yes }).create(draft);
-    out(created, o.json, () => `Created ${created.key} (${created.status}) \u2014 ${created.title}`);
+    try {
+      const created = await resolveProvider(process.cwd(), { yes: o.yes }).create(draft);
+      out(created, o.json, () => `Created ${created.key} (${created.status}) \u2014 ${created.title}`);
+    } catch (err) {
+      if (err instanceof LegacyDataError) {
+        out(err.report, o.json, () => renderLegacyRefusal(err.report));
+        process.exitCode = 1;
+        return;
+      }
+      throw err;
+    }
   });
   tickets.command("list").description("List all tickets").option("--json", "machine-readable output", false).action(async (o) => {
     const refs = await resolveProvider().list();
@@ -1577,11 +2257,16 @@ ${blocked}`;
       process.exitCode = 1;
       return;
     }
-    const t = await resolveProvider(process.cwd(), { yes: o.yes }).setStatus(key, status);
+    const t = await resolveProvider(process.cwd(), { yes: o.yes }).setStatus(
+      key,
+      status
+    );
     out(t, o.json, () => `${t.key} \u2192 ${t.status}`);
   });
   tickets.command("start <key>").description("Mark a ticket started (In progress)").option("--branch <name>").option("--yes", "execute remote mutations (default: dry-run)", false).option("--json", "machine-readable output", false).action(async (key, o) => {
-    const t = await resolveProvider(process.cwd(), { yes: o.yes }).start(key, { branch: o.branch });
+    const t = await resolveProvider(process.cwd(), { yes: o.yes }).start(key, {
+      branch: o.branch
+    });
     out(t, o.json, () => `${t.key} \u2192 ${t.status}`);
   });
   tickets.command("delete <key>").description("Delete a ticket").option("--yes", "execute remote mutations (default: dry-run)", false).option("--json", "machine-readable output", false).action(async (key, o) => {
@@ -1593,7 +2278,7 @@ ${blocked}`;
     out({ nextId: id }, o.json, () => id);
   });
   tickets.command("amend <key>").description("Edit a ticket (from --file patch or flags)").option("-f, --file <path>", "JSON patch (validated against the template)").option("-s, --summary <text>").option("--notes <text>").option("--ac <criterion>", "replace acceptance criteria (repeatable)", collect2, []).option("--dep <key>", "replace dependencies (repeatable)", collect2, []).option("--pr <ref>", "link a PR").option("--yes", "execute remote mutations (default: dry-run)", false).option("--json", "machine-readable output", false).action(async (key, o) => {
-    const patch = o.file ? TicketSchema.partial().parse(JSON.parse(readFileSync6(String(o.file), "utf-8"))) : buildPatch(o);
+    const patch = o.file ? TicketSchema.partial().parse(JSON.parse(readFileSync7(String(o.file), "utf-8"))) : buildPatch(o);
     const t = await resolveProvider(process.cwd(), { yes: o.yes }).amend(key, patch);
     out(t, o.json, () => `Amended ${t.key}`);
   });
@@ -1615,7 +2300,11 @@ ${blocked}`;
       const t = await provider.amend(key, { dependencies: deps });
       out(t.dependencies, o.json, () => `${key} deps: ${t.dependencies.join(", ") || "(none)"}`);
     } else {
-      out(current.dependencies, o.json, () => `${key} deps: ${current.dependencies.join(", ") || "(none)"}`);
+      out(
+        current.dependencies,
+        o.json,
+        () => `${key} deps: ${current.dependencies.join(", ") || "(none)"}`
+      );
     }
   });
   tickets.command("hand-off <key>").description("End of slice: move to To review and optionally link the PR").option("--pr <ref>", "link the PR at hand-off").option("--yes", "execute remote mutations (default: dry-run)", false).option("--json", "machine-readable output", false).action(async (key, o) => {
@@ -1629,6 +2318,13 @@ ${blocked}`;
 function collect2(value, previous) {
   return previous.concat([value]);
 }
+function renderLegacyRefusal(report) {
+  const list = report.folders.map((f) => `docs/tickets/${f}`).join(" and ");
+  const files = `${report.ticketCount} ticket file${report.ticketCount === 1 ? "" : "s"}`;
+  return `Refusing to create: legacy ticket data detected under ${list} (at least ${files}).
+kodi uses a clean-start model and will not migrate, move, or modify legacy tickets.
+Move or remove the legacy tickets under ${list}, then re-run.`;
+}
 function buildPatch(o) {
   const patch = {};
   if (o.summary !== void 0) patch.summary = o.summary;
@@ -1641,13 +2337,14 @@ function buildPatch(o) {
 
 // package.json
 var name = "kodi-dev";
-var version = "0.1.1";
+var version = "1.0.0";
 var description = "kodi.dev \u2014 Claude Code-native agent orchestrator CLI";
 
 // src/index.ts
 var program = new Command();
 program.name(name).description(description).version(version, "-v, --version", "output the current version");
 registerTicketsCommand(program);
+registerServeCommand(program);
 registerPrCommand(program);
 registerHookCommand(program);
 registerInitCommand(program);