recursive-board 0.2.0 → 0.3.0

package/dist/wi/wi.js

@@ -144,6 +144,47 @@ function removeKey(text, key) {
 function defaultEnd(text) {
   return text.includes("\r\n") ? "\r\n" : "\n";
 }
+function getList(text, key) {
+  const block = splitBlock(text);
+  if (!block) return void 0;
+  const entry = readEntries(block.lines).find((e) => e.key === key);
+  if (!entry) return void 0;
+  const first = KEY_LINE.exec(block.lines[entry.start])?.[2]?.trim() ?? "";
+  let parts;
+  if (first.startsWith("[")) {
+    parts = first.replace(/^\[|\]$/g, "").split(",");
+  } else if (first !== "") {
+    parts = first.split(/[,\s]+/);
+  } else {
+    parts = block.lines.slice(entry.start + 1, entry.end).map((line2) => /^[ \t]*-[ \t]+(.*)$/.exec(line2)?.[1] ?? "");
+  }
+  return parts.map((part) => {
+    const value = parseScalar(part);
+    return typeof value === "string" ? value : value === void 0 ? "" : String(value);
+  }).map((part) => part.trim()).filter((part) => part !== "");
+}
+function setList(text, key, values) {
+  if (values.length === 0) return removeKey(text, key);
+  const block = splitBlock(text);
+  if (!block) throw new Error(`cannot set "${key}": the file has no frontmatter`);
+  const entry = readEntries(block.lines).find((e) => e.key === key);
+  const current = getList(text, key);
+  if (entry && current !== void 0 && current.length === values.length && current.every((value, i) => value === values[i]) && block.lines.slice(entry.start + 1, entry.end).every((line2) => /^[ \t]*-[ \t]/.test(line2))) {
+    return text;
+  }
+  const eol = defaultEnd(text);
+  const replacement = [`${key}:`, ...values.map((value) => `  - ${formatScalar(value)}`)];
+  const lines = [...block.lines];
+  const ends = [...block.ends];
+  if (entry) {
+    lines.splice(entry.start, entry.end - entry.start, ...replacement);
+    ends.splice(entry.start, entry.end - entry.start, ...replacement.map(() => eol));
+  } else {
+    lines.push(...replacement);
+    ends.push(...replacement.map(() => eol));
+  }
+  return rewrite(text, block, lines, ends);
+}
 
 // src/shared/schema.ts
 var STATUSES = ["backlog", "options", "doing", "done"];
@@ -169,9 +210,8 @@ var OPTIONAL_FIELDS = [
   "archived",
   // docs/adr/0007-archive-is-a-frontmatter-flag.md: a flag, not a status.
   "area"
-  // docs/adr/0028-area-work-items.md: an ongoing space with no status.
+  // docs/adr/0028-area-work-items.md: an ongoing space that keeps its status.
 ];
-var INHERITED_FIELDS = ["owner", "agent"];
 var WORK_ITEM_TYPE = "work-item";
 function isArea(value) {
   return value === true;
@@ -228,7 +268,10 @@ var WI_CONFIG_FILE = ".wi.json";
 var DEFAULT_VAULT_CONFIG = {
   workItemFolder: "Boards",
   defaultRoot: null,
-  extraSections: []
+  extraSections: [],
+  maxAgents: null,
+  autoPromote: true,
+  areaTags: false
 };
 function parseVaultConfig(text) {
   if (text === null) return { ...DEFAULT_VAULT_CONFIG, extraSections: [] };
@@ -244,6 +287,9 @@ function parseVaultConfig(text) {
   const folderValue = "workItemFolder" in value ? value.workItemFolder : void 0;
   const rootValue = "defaultRoot" in value ? value.defaultRoot : void 0;
   const sectionsValue = "extraSections" in value ? value.extraSections : void 0;
+  const maxAgentsValue = "maxAgents" in value ? value.maxAgents : void 0;
+  const autoPromoteValue = "autoPromote" in value ? value.autoPromote : void 0;
+  const areaTagsValue = "areaTags" in value ? value.areaTags : void 0;
   let workItemFolder = DEFAULT_VAULT_CONFIG.workItemFolder;
   if (folderValue !== void 0) {
     if (typeof folderValue !== "string") {
@@ -274,7 +320,22 @@ function parseVaultConfig(text) {
       extraSections.push(heading);
     }
   }
-  return { workItemFolder, defaultRoot, extraSections };
+  let maxAgents = null;
+  if (maxAgentsValue !== void 0 && maxAgentsValue !== null) {
+    if (typeof maxAgentsValue !== "number" || !Number.isSafeInteger(maxAgentsValue) || maxAgentsValue < 0) {
+      throw new Error(`${WI_CONFIG_FILE}: maxAgents must be a non-negative whole number or null.`);
+    }
+    maxAgents = maxAgentsValue;
+  }
+  if (autoPromoteValue !== void 0 && typeof autoPromoteValue !== "boolean") {
+    throw new Error(`${WI_CONFIG_FILE}: autoPromote must be true or false.`);
+  }
+  const autoPromote = autoPromoteValue ?? DEFAULT_VAULT_CONFIG.autoPromote;
+  if (areaTagsValue !== void 0 && typeof areaTagsValue !== "boolean") {
+    throw new Error(`${WI_CONFIG_FILE}: areaTags must be true or false.`);
+  }
+  const areaTags = areaTagsValue ?? DEFAULT_VAULT_CONFIG.areaTags;
+  return { workItemFolder, defaultRoot, extraSections, maxAgents, autoPromote, areaTags };
 }
 
 // src/shared/archive.ts
@@ -305,6 +366,15 @@ function activeDescendant(item, childrenOf, statusOf) {
 }
 
 // src/cli/vault.ts
+function maxAgentsForRun(vault, env = process.env) {
+  const override = env["WI_MAX_AGENTS"];
+  if (override === void 0) return vault.config.maxAgents;
+  if (override.trim() === "") return null;
+  if (!/^\d+$/.test(override) || !Number.isSafeInteger(Number(override))) {
+    throw new Error("WI_MAX_AGENTS must be a non-negative whole number.");
+  }
+  return Number(override);
+}
 var MARKDOWN = /\.md$/i;
 function wiConfigDir(env = process.env) {
   const xdg = env["XDG_CONFIG_HOME"];
@@ -550,18 +620,21 @@ function isMissingFile(error) {
 }
 
 // src/cli/commands/new.ts
-import { existsSync as existsSync2 } from "node:fs";
-import { join as join3 } from "node:path";
+import { existsSync as existsSync3 } from "node:fs";
+import { join as join4 } from "node:path";
 
 // src/cli/write.ts
-import { writeFile as writeFile2, rename as rename2 } from "node:fs/promises";
+import { writeFile as writeFile2, rename as rename2, readFile as readFile2, mkdir as mkdir2, rm, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { tmpdir } from "node:os";
 import { dirname as dirname2, join as join2 } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
 
 // src/shared/edits.ts
 function applyEdits(text, edits) {
   let out = text;
   for (const edit of edits) {
-    out = edit.op === "set" ? setKey(out, edit.key, edit.value) : removeKey(out, edit.key);
+    out = edit.op === "set" ? setKey(out, edit.key, edit.value) : edit.op === "list" ? setList(out, edit.key, edit.values) : removeKey(out, edit.key);
   }
   return out;
 }
@@ -572,15 +645,46 @@ function withStamp(edits, stamp = today()) {
 
 // src/cli/write.ts
 async function writeAtomic(path, text) {
-  const temp = join2(dirname2(path), `.wi-${process.pid}-${Date.now()}.tmp`);
+  const temp = join2(dirname2(path), `.wi-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.tmp`);
   await writeFile2(temp, text, "utf8");
   await rename2(temp, path);
 }
+var LOCK_WAIT_MS = 5e3;
+var LOCK_STALE_MS = 3e4;
+async function withFileLock(path, fn) {
+  const lock = join2(tmpdir(), `wi-lock-${createHash("sha1").update(path).digest("hex")}`);
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  for (; ; ) {
+    try {
+      await mkdir2(lock);
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const age = await stat(lock).then((s) => Date.now() - s.mtimeMs, () => 0);
+      if (age > LOCK_STALE_MS) {
+        await rm(lock, { recursive: true, force: true });
+        continue;
+      }
+      if (Date.now() > deadline) {
+        throw new Error(`another wi process is writing ${path}. Retry. If no wi runs, remove ${lock}.`);
+      }
+      await sleep(20);
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    await rm(lock, { recursive: true, force: true });
+  }
+}
 async function editItem(item, edits, editBody = (text) => text) {
-  if (editBody(applyEdits(item.text, edits)) === item.text) return item.text;
-  const text = editBody(applyEdits(item.text, withStamp(edits)));
-  await writeAtomic(item.path, text);
-  return text;
+  return withFileLock(item.path, async () => {
+    const current = await readFile2(item.path, "utf8");
+    if (editBody(applyEdits(current, edits)) === current) return current;
+    const text = editBody(applyEdits(current, withStamp(edits)));
+    await writeAtomic(item.path, text);
+    return text;
+  });
 }
 
 // src/shared/templates.ts
@@ -599,13 +703,13 @@ var TEMPLATES = [
     name: "first-board-card",
     description: "A short guide to adding and moving cards on your first board.",
     sections: [
-      { heading: "Getting started", starter: "Add cards from a board column. To move this card, open its card menu and choose \u201CMove to\u2026\u201D." },
+      { heading: "Getting started", starter: "Add cards from a board column. Use Promote at the top of this card to give it its own board. To move this card, open its card menu and choose \u201CMove to\u2026\u201D." },
       { heading: "Notes" }
     ]
   },
   {
     name: "area",
-    description: "An ongoing area of work with no status.",
+    description: "An ongoing area of work.",
     area: true,
     sections: [
       { heading: "Objective" },
@@ -626,15 +730,45 @@ function requireTemplate(name = DEFAULT_TEMPLATE) {
   if (template) return template;
   throw new Error(`no template called "${name}". There is: ${templateNames().join(", ")}.`);
 }
-function renderBody(template, extraSections = []) {
-  const parts = [];
+var BRIEF_HEADINGS = { objective: "Objective", context: "Context", criteria: "Acceptance Criteria" };
+function briefGaps(template, brief = {}) {
+  const headings2 = new Set(template.sections.map((s) => s.heading));
+  const gaps = [];
+  if (headings2.has(BRIEF_HEADINGS.objective) && !brief.objective?.trim()) gaps.push(BRIEF_HEADINGS.objective);
+  if (headings2.has(BRIEF_HEADINGS.criteria) && !brief.criteria?.some((c) => c.trim() !== "")) {
+    gaps.push(BRIEF_HEADINGS.criteria);
+  }
+  return gaps;
+}
+function briefContent(brief) {
+  const content = /* @__PURE__ */ new Map();
+  const objective = brief.objective?.trim();
+  if (objective) content.set(BRIEF_HEADINGS.objective, objective);
+  const context = (brief.context ?? []).map((c) => c.trim()).filter((c) => c !== "");
+  if (context.length > 0) content.set(BRIEF_HEADINGS.context, context.join("\n\n"));
+  const criteria = (brief.criteria ?? []).map((c) => c.trim()).filter((c) => c !== "");
+  for (const line2 of criteria) {
+    if (/[\r\n]/.test(line2)) throw new Error("each acceptance criterion must be one line.");
+  }
+  if (criteria.length > 0) content.set(BRIEF_HEADINGS.criteria, criteria.map((c) => `- ${c}`).join("\n"));
+  return content;
+}
+function renderBody(template, extraSections = [], brief = {}) {
+  const content = briefContent(brief);
   const sections = [
     ...template.sections,
     ...extraSections.map((heading) => ({ heading, starter: "- " }))
   ];
+  for (const heading of content.keys()) {
+    if (!sections.some((s) => s.heading === heading)) {
+      throw new Error(`template "${template.name}" has no ${heading} section.`);
+    }
+  }
+  const parts = [];
   for (const section of sections) {
     parts.push(`## ${section.heading}`, "");
-    if (section.starter !== void 0) parts.push(section.starter, "");
+    const filled = content.get(section.heading) ?? section.starter;
+    if (filled !== void 0) parts.push(filled, "");
   }
   return parts.join("\n");
 }
@@ -647,13 +781,13 @@ function renderVaultTemplate(template, defaultRoot = null, extraSections = []) {
     created: "",
     updated: ""
   };
+  placeholders["status"] = "backlog";
   if (template.area) placeholders["area"] = "true";
-  else placeholders["status"] = "backlog";
-  const fields = template.area ? CORE_FIELDS.filter((field) => field !== "status") : CORE_FIELDS;
+  const fields = CORE_FIELDS;
   const lines = fields.filter((field) => field in placeholders).map(
     (field) => `${field}: ${placeholders[field]}`.trimEnd()
   );
-  if (template.area) lines.splice(3, 0, "area: true");
+  if (template.area) lines.splice(4, 0, "area: true");
   return `---
 ${lines.join("\n")}
 ---
@@ -662,6 +796,12 @@ ${renderBody(template, extraSections)}`;
 }
 
 // src/shared/work-item.ts
+function inheritedChildFields(parent, status, overrides = {}) {
+  return {
+    owner: overrides.owner ?? parent.owner,
+    agent: overrides.agent ?? (status === "doing" ? parent.agent : void 0)
+  };
+}
 function renderWorkItem(item, extraSections = []) {
   const template = requireTemplate(item.template);
   if (Boolean(template.area) !== (item.area === true)) {
@@ -672,62 +812,22 @@ function renderWorkItem(item, extraSections = []) {
     ["id", item.id],
     ["title", item.title]
   ];
+  fields.push(["status", item.status]);
   if (item.area) fields.push(["area", true]);
-  else fields.push(["status", item.status]);
   fields.push(["parent", formatWikilink(item.parentStem)]);
   if (item.owner !== void 0 && item.owner !== "") fields.push(["owner", item.owner]);
   if (item.agent !== void 0 && item.agent !== "") fields.push(["agent", item.agent]);
   if (item.priority !== void 0) fields.push(["priority", item.priority]);
   fields.push(["created", item.created], ["updated", item.updated]);
-  const frontmatter = fields.map(([key, value]) => `${key}: ${formatScalar(value)}`).join("\n");
+  const lines = fields.map(([key, value]) => `${key}: ${formatScalar(value)}`);
+  if (item.tags !== void 0 && item.tags.length > 0) {
+    lines.push("tags:", ...item.tags.map((tag) => `  - ${formatScalar(tag)}`));
+  }
   return `---
-${frontmatter}
+${lines.join("\n")}
 ---
 
-${renderBody(template, extraSections)}`;
-}
-
-// src/cli/commands/new.ts
-async function createItem(vault, options) {
-  const title = options.title.trim();
-  if (title === "") throw new Error("a work item needs a title");
-  const parentRef = options.parent ?? vault.config.defaultRoot ?? "";
-  if (parentRef.trim() === "") {
-    throw new Error("a work item needs a --parent. Only the root has none.");
-  }
-  const template = requireTemplate(options.template);
-  const status = options.status ?? "backlog";
-  if (template.area && options.status !== void 0) {
-    throw new Error("an area cannot have a status");
-  }
-  if (!template.area && !isStatus(status)) {
-    throw new Error(`"${status}" is not a status. Use backlog, options, doing or done.`);
-  }
-  const parent = vault.resolve(parentRef);
-  const id = newId(vault.takenIds);
-  const stem = fileNameFor(title, id, vault.takenStems);
-  const relPath = `${vault.config.workItemFolder}/${stem}.md`;
-  const path = join3(vault.root, ...vault.config.workItemFolder.split("/"), `${stem}.md`);
-  if (existsSync2(path)) {
-    throw new Error(`${relPath} already exists. Refusing to overwrite it.`);
-  }
-  const stamp = today();
-  const common = {
-    id,
-    title,
-    parentStem: parent.stem,
-    created: stamp,
-    updated: stamp,
-    template: options.template
-  };
-  const fields = template.area ? { ...common, area: true } : { ...common, status };
-  for (const field of INHERITED_FIELDS) {
-    const value = options[field] ?? parent.frontmatter.get(field);
-    if (value !== void 0 && value !== "") fields[field] = String(value);
-  }
-  if (options.priority !== void 0) fields.priority = options.priority;
-  await writeAtomic(path, renderWorkItem(fields, vault.config.extraSections));
-  return { id, stem, relPath, path, parentStem: parent.stem };
+${renderBody(template, extraSections, item.brief)}`;
 }
 
 // src/shared/transitions.ts
@@ -741,13 +841,15 @@ function statusEdits(from, to, hasPrevStatus) {
   }
   return edits;
 }
-function claimEdits(from, currentAgent, agent, hasPrevStatus, hasDoingChild) {
+function claimEdits(from, currentAgent, agent, hasPrevStatus, hasOtherDoingChild) {
   if (from === "done") throw new Error("a done card cannot be claimed.");
   if (currentAgent && currentAgent !== agent) {
     throw new Error(`already claimed by ${currentAgent}. Release that claim first.`);
   }
   if (currentAgent === agent && from === "doing") return null;
-  if (hasDoingChild) throw new Error("this board has a child in doing. Release or finish the child first.");
+  if (hasOtherDoingChild) {
+    throw new Error("this board has a child in doing that another agent or a person works. Release or finish that child first.");
+  }
   const status = statusEdits(from, "doing", hasPrevStatus);
   if (currentAgent === agent) return status;
   return [...status ?? [], { op: "set", key: "agent", value: agent }];
@@ -755,6 +857,13 @@ function claimEdits(from, currentAgent, agent, hasPrevStatus, hasDoingChild) {
 function releaseEdits(from, hasPrevStatus) {
   return [...statusEdits(from, "options", hasPrevStatus) ?? [], { op: "remove", key: "agent" }];
 }
+function boardEdits(promoted) {
+  return promoted ? [{ op: "set", key: "board", value: true }] : [{ op: "remove", key: "board" }];
+}
+function firstChildPromotion(parent, autoPromote) {
+  if (!autoPromote || parent.isRoot || parent.area || parent.hasBoardKey || parent.childCount > 0) return null;
+  return boardEdits(true);
+}
 function moveEdits(currentParentStem, targetStem) {
   if (currentParentStem !== null && currentParentStem.toLowerCase() === targetStem.toLowerCase()) {
     return null;
@@ -776,6 +885,219 @@ function moveRefusal(check) {
   return null;
 }
 
+// src/shared/labels.ts
+var LABEL_COLOURS = [
+  "red",
+  "orange",
+  "yellow",
+  "green",
+  "cyan",
+  "blue",
+  "purple",
+  "pink"
+];
+function labelColour(label2) {
+  const key = label2.trim().replace(/^#/, "").toLowerCase();
+  let hash = 0;
+  for (let i = 0; i < key.length; i++) {
+    hash = hash * 31 + key.charCodeAt(i) >>> 0;
+  }
+  return LABEL_COLOURS[hash % LABEL_COLOURS.length];
+}
+
+// src/shared/area-tags.ts
+var AREA_TAG_PREFIX = "area/";
+function isAreaTag(tag) {
+  return tag.replace(/^#/, "").toLowerCase().startsWith(AREA_TAG_PREFIX);
+}
+function areaSlug(title) {
+  const slug = title.toLowerCase().normalize("NFKD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9_]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug === "" ? "untitled" : slug;
+}
+function areaTagFor(chain) {
+  const areas = chain.filter((node2) => node2.area).reverse();
+  if (areas.length === 0) return null;
+  return `${AREA_TAG_PREFIX}${areas.map((node2) => areaSlug(node2.title)).join("/")}`;
+}
+function withAreaTag(tags, tag) {
+  const kept = tags.filter((existing) => !isAreaTag(existing));
+  return tag === null ? kept : [...kept, tag];
+}
+function hasAreaTag(tags, tag) {
+  const current = tags.filter(isAreaTag).map((t) => t.replace(/^#/, ""));
+  return tag === null ? current.length === 0 : current.length === 1 && current[0] === tag;
+}
+var RGB = {
+  red: 15282503,
+  orange: 15496448,
+  yellow: 14724096,
+  green: 571726,
+  cyan: 49084,
+  blue: 552413,
+  purple: 7885550,
+  pink: 13973892
+};
+function shade(rgb, amount) {
+  const target = amount >= 0 ? 255 : 0;
+  const mix = (channel) => Math.round(channel + (target - channel) * Math.abs(amount));
+  return mix(rgb >> 16 & 255) << 16 | mix(rgb >> 8 & 255) << 8 | mix(rgb & 255);
+}
+function areaColourGroups(tags) {
+  const unique = [...new Set([...tags].map((t) => t.replace(/^#/, "")).filter(isAreaTag))];
+  const depth = (tag) => tag.split("/").length - 1;
+  unique.sort((a, b) => depth(b) - depth(a) || a.localeCompare(b));
+  return unique.flatMap((tag) => {
+    const top = tag.split("/").slice(0, 2).join("/");
+    const base = shade(RGB[labelColour(top)], Math.min(0.6, (depth(tag) - 1) * 0.3));
+    return [
+      { query: `tag:#${tag} ([board:true] OR [area:true])`, color: { a: 1, rgb: shade(base, -0.3) } },
+      { query: `tag:#${tag}`, color: { a: 1, rgb: base } }
+    ];
+  });
+}
+function isAreaColourGroup(group) {
+  if (typeof group !== "object" || group === null || !("query" in group)) return false;
+  return typeof group.query === "string" && group.query.startsWith(`tag:#${AREA_TAG_PREFIX}`);
+}
+
+// src/cli/commands/retag.ts
+import { readFile as readFile3 } from "node:fs/promises";
+import { existsSync as existsSync2 } from "node:fs";
+import { join as join3 } from "node:path";
+function node(item) {
+  return { title: item.title ?? item.stem, area: item.area };
+}
+function chainOf(vault, item) {
+  const chain = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (let current = item; current; current = vault.resolveLink(current.parent)) {
+    if (seen.has(current.relPath)) break;
+    seen.add(current.relPath);
+    chain.push(node(current));
+  }
+  return chain;
+}
+function expectedAreaTag(vault, item) {
+  return areaTagFor(chainOf(vault, item));
+}
+function tagsOf(item) {
+  return getList(item.text, "tags") ?? [];
+}
+function staleAreaTags(vault) {
+  return vault.items.flatMap((item) => {
+    if (!item.frontmatter.has("parent")) return [];
+    const tags = tagsOf(item);
+    const tag = expectedAreaTag(vault, item);
+    return hasAreaTag(tags, tag) ? [] : [{ item, from: tags, to: withAreaTag(tags, tag) }];
+  });
+}
+function requireAreaTags(vault) {
+  if (!vault.config.areaTags) {
+    throw new Error('area tags are off in this vault. Set "areaTags": true in .wi.json first.');
+  }
+}
+async function retag(vault, dryRun) {
+  requireAreaTags(vault);
+  const stale = staleAreaTags(vault);
+  if (!dryRun) {
+    for (const entry of stale) await editItem(entry.item, [{ op: "list", key: "tags", values: entry.to }]);
+  }
+  return stale;
+}
+async function writeGraphColours(vault, configDir = ".obsidian") {
+  requireAreaTags(vault);
+  const path = join3(vault.root, configDir, "graph.json");
+  if (!existsSync2(join3(vault.root, configDir))) {
+    throw new Error(`${configDir}/ is missing, so this vault has never been opened in Obsidian. Open it once, then retry.`);
+  }
+  let config = {};
+  if (existsSync2(path)) {
+    const parsed = JSON.parse(await readFile3(path, "utf8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error(`${configDir}/graph.json is not a JSON object. Nothing was written.`);
+    }
+    config = { ...parsed };
+  }
+  const tags = vault.items.flatMap((item) => {
+    const tag = expectedAreaTag(vault, item);
+    return tag === null ? [] : [tag];
+  });
+  const groups = areaColourGroups(tags);
+  const existing = Array.isArray(config["colorGroups"]) ? config["colorGroups"] : [];
+  const kept = existing.filter((group) => !isAreaColourGroup(group));
+  config["colorGroups"] = [...groups, ...kept];
+  await writeAtomic(path, `${JSON.stringify(config, null, 2)}
+`);
+  return { path: `${configDir}/graph.json`, groups: groups.length, kept: kept.length };
+}
+
+// src/cli/commands/new.ts
+async function createItem(vault, options) {
+  const title = options.title.trim();
+  if (title === "") throw new Error("a work item needs a title");
+  const parentRef = options.parent ?? vault.config.defaultRoot ?? "";
+  if (parentRef.trim() === "") {
+    throw new Error("a work item needs a --parent. Only the root has none.");
+  }
+  const template = requireTemplate(options.template);
+  const status = options.status ?? "backlog";
+  if (!isStatus(status)) {
+    throw new Error(`"${status}" is not a status. Use backlog, options, doing or done.`);
+  }
+  const parent = vault.resolve(parentRef);
+  const gaps = briefGaps(template, options.brief);
+  if (options.strict && gaps.length > 0) {
+    throw new Error(`the card has no ${gaps.join(" or ")}. Pass --objective and --criteria, or drop --strict.`);
+  }
+  renderBody(template, vault.config.extraSections, options.brief);
+  const id = newId(vault.takenIds);
+  const stem = fileNameFor(title, id, vault.takenStems);
+  const relPath = `${vault.config.workItemFolder}/${stem}.md`;
+  const path = join4(vault.root, ...vault.config.workItemFolder.split("/"), `${stem}.md`);
+  if (existsSync3(path)) {
+    throw new Error(`${relPath} already exists. Refusing to overwrite it.`);
+  }
+  const stamp = today();
+  const common = {
+    id,
+    title,
+    parentStem: parent.stem,
+    created: stamp,
+    updated: stamp,
+    template: options.template,
+    brief: options.brief
+  };
+  const inherited = inheritedChildFields({
+    owner: textField(parent.frontmatter.get("owner")),
+    agent: textField(parent.frontmatter.get("agent"))
+  }, status, options);
+  const fields = template.area ? { ...common, ...inherited, area: true, status } : { ...common, ...inherited, status };
+  if (options.priority !== void 0) fields.priority = options.priority;
+  const areaTag = vault.config.areaTags ? areaTagFor([{ title, area: template.area === true }, ...chainOf(vault, parent)]) : null;
+  if (areaTag !== null) fields.tags = [areaTag];
+  await writeAtomic(path, renderWorkItem(fields, vault.config.extraSections));
+  const promotion = firstChildPromotion({
+    isRoot: parent.parent === null && !parent.frontmatter.has("parent"),
+    area: parent.area,
+    hasBoardKey: parent.frontmatter.has("board"),
+    childCount: vault.childrenOf(parent).length
+  }, vault.config.autoPromote);
+  if (promotion) await editItem(parent, promotion);
+  return {
+    id,
+    stem,
+    relPath,
+    path,
+    parentStem: parent.stem,
+    promotedParent: promotion !== null,
+    gaps,
+    renamed: stem !== fileNameStem(title)
+  };
+}
+function textField(value) {
+  return value === void 0 || value === null ? void 0 : String(value);
+}
+
 // src/cli/commands/status.ts
 async function setStatus(vault, ref, status) {
   if (!isStatus(status)) {
@@ -790,11 +1112,17 @@ async function setStatus(vault, ref, status) {
   const from = item.status;
   const edits = statusEdits(from, status, item.frontmatter.has("prev_status"));
   if (edits === null) {
-    return { item, from, to: status, recorded: void 0, changed: false };
+    return { item, from, to: status, recorded: void 0, changed: false, parentReady: void 0 };
   }
   const recorded = status === "done" ? from : void 0;
   await editItem(item, edits);
-  return { item, from, to: status, recorded, changed: true };
+  return { item, from, to: status, recorded, changed: true, parentReady: status === "done" ? readyParent(vault, item) : void 0 };
+}
+function readyParent(vault, item) {
+  const parent = vault.resolveLink(item.parent);
+  if (parent === void 0 || !parent.frontmatter.has("parent") || parent.area || parent.status === "done") return void 0;
+  const open = vault.childrenOf(parent).filter((child) => !child.archived && child !== item && child.status !== "done");
+  return open.length === 0 ? parent : void 0;
 }
 
 // src/shared/notes.ts
@@ -839,9 +1167,17 @@ function appendNote(text, line2) {
   if (content === "") return `${text.slice(0, start)}${eol}${eol}${line2}${eol}${text.slice(end)}`;
   const trailing = /(?:\r?\n[ \t]*)*$/.exec(content)?.[0] ?? "";
   const prose = content.slice(0, content.length - trailing.length);
-  const insertion = prose === "" ? `${content}${line2}${eol}${next ? eol : ""}` : `${prose}${eol}${line2}${trailing || eol}`;
+  const insertion = prose === "" ? `${eol}${eol}${line2}${eol}${next ? eol : ""}` : `${prose}${eol}${line2}${trailing || eol}`;
   return text.slice(0, start) + insertion + text.slice(end);
 }
+function noteLine(text, agent, now = /* @__PURE__ */ new Date()) {
+  const body = text.trim();
+  if (body === "") throw new Error("a note needs text.");
+  if (/[\r\n]/.test(body)) throw new Error("a note must be one line.");
+  const pad = (n) => String(n).padStart(2, "0");
+  const who = agent?.trim() ? `, ${agent.trim()}` : "";
+  return `- ${today(now)} ${pad(now.getHours())}:${pad(now.getMinutes())}${who}: ${body}`;
+}
 
 // src/cli/commands/claim-release.ts
 async function claimItem(vault, ref, agent) {
@@ -850,12 +1186,16 @@ async function claimItem(vault, ref, agent) {
   if (item.parent === null) throw new Error(`${item.relPath} is a root, and a root cannot be claimed.`);
   const current = item.frontmatter.get("agent");
   const currentAgent = typeof current === "string" && current.trim() !== "" ? current : void 0;
+  const holding = currentAgent === agent && item.status === "doing";
+  if (!holding && item.frontmatter.get("blocked") === true) {
+    throw new Error(`${item.relPath} is blocked. Clear its blocked flag when the block is gone, or claim another card.`);
+  }
   const edits = claimEdits(
     item.status,
     currentAgent,
     agent,
     item.frontmatter.has("prev_status"),
-    item.board && vault.childrenOf(item).some((child) => child.status === "doing")
+    item.board && vault.childrenOf(item).some((child) => child.status === "doing" && child.frontmatter.get("agent") !== agent)
   );
   if (edits === null) return { item, agent, from: item.status, to: "doing", changed: false };
   await editItem(item, edits);
@@ -877,6 +1217,16 @@ async function releaseItem(vault, ref, reason, where) {
   return { item, agent: current, from: item.status, to: "options", reason, where, changed: true };
 }
 
+// src/cli/commands/note.ts
+async function addNote(vault, ref, text, agent, now = /* @__PURE__ */ new Date()) {
+  const item = vault.resolve(ref);
+  const held = item.frontmatter.get("agent");
+  const who = agent ?? (typeof held === "string" && held.trim() !== "" ? held : void 0);
+  const line2 = noteLine(text, who, now);
+  await editItem(item, [], (body) => appendNote(body, line2));
+  return { item, line: line2 };
+}
+
 // src/cli/commands/children.ts
 function listChildren(vault, ref, options = {}) {
   const { status, recursive = false, archived = false } = options;
@@ -929,6 +1279,12 @@ async function validate(vault) {
   checkDefaultRoot(vault, report);
   checkRoots(vault, report);
   checkCycles(vault, report);
+  if (vault.config.areaTags) {
+    for (const { item, to } of staleAreaTags(vault)) {
+      const tag = to.find(isAreaTag);
+      report("area-tag-stale", "warning", item.relPath, item.id, tag ? `should carry the area tag ${tag}. Run wi retag.` : "carries an area tag but sits in no area. Run wi retag.");
+    }
+  }
   problems.sort((a, b) => a.relPath.localeCompare(b.relPath) || a.rule.localeCompare(b.rule));
   const errorCount = problems.filter((p) => p.severity === "error").length;
   return {
@@ -1011,14 +1367,11 @@ function checkItem(item, vault, report) {
   if (item.title === void 0) say("title-missing", "error", "has no title.");
   const rawStatus = item.frontmatter.get("status");
   const isRoot = !item.frontmatter.has("parent");
-  const isArea2 = item.frontmatter.get("area") === true;
   const rawArea = item.frontmatter.get("area");
   if (rawArea !== void 0 && rawArea !== true) {
     say("area-invalid", "error", `carries area: ${rawArea}. The only valid marker is area: true.`);
   }
-  if (isArea2 && rawStatus !== void 0) {
-    say("status-on-area", "error", "is an area and carries a status. Areas have no status; remove the status field.");
-  } else if (isRoot) {
+  if (isRoot) {
     if (rawStatus !== void 0) {
       say(
         "status-on-root",
@@ -1026,9 +1379,9 @@ function checkItem(item, vault, report) {
         `is a root and carries status "${rawStatus}". A root is not a card in anyone's column, so it takes no status.`
       );
     }
-  } else if (!isArea2 && rawStatus === void 0) {
+  } else if (rawStatus === void 0) {
     say("status-missing", "error", `has no status. Use one of: ${STATUSES.join(", ")}.`);
-  } else if (!isArea2 && !isStatus(rawStatus)) {
+  } else if (!isStatus(rawStatus)) {
     say(
       "status-invalid",
       "error",
@@ -1166,28 +1519,28 @@ function checkCycles(vault, report) {
 }
 
 // src/cli/commands/template.ts
-import { readFile as readFile2 } from "node:fs/promises";
-import { existsSync as existsSync3 } from "node:fs";
-import { mkdir as mkdir2 } from "node:fs/promises";
-import { join as join4 } from "node:path";
+import { readFile as readFile4 } from "node:fs/promises";
+import { existsSync as existsSync4 } from "node:fs";
+import { mkdir as mkdir3 } from "node:fs/promises";
+import { join as join5 } from "node:path";
 var TEMPLATES_FOLDER = "Templates";
 function listTemplates() {
   return TEMPLATES;
 }
 async function writeTemplates(vault) {
-  const folder = join4(vault.root, TEMPLATES_FOLDER);
-  await mkdir2(folder, { recursive: true });
+  const folder = join5(vault.root, TEMPLATES_FOLDER);
+  await mkdir3(folder, { recursive: true });
   const written = [];
   for (const template of TEMPLATES) {
-    const path = join4(folder, `${template.name}.md`);
+    const path = join5(folder, `${template.name}.md`);
     const relPath = `${TEMPLATES_FOLDER}/${template.name}.md`;
     const next = renderVaultTemplate(template, vault.config.defaultRoot, vault.config.extraSections);
-    if (!existsSync3(path)) {
+    if (!existsSync4(path)) {
       await writeAtomic(path, next);
       written.push({ name: template.name, relPath, outcome: "created" });
       continue;
     }
-    const current = await readFile2(path, "utf8");
+    const current = await readFile4(path, "utf8");
     if (current === next) {
       written.push({ name: template.name, relPath, outcome: "unchanged" });
       continue;
@@ -1199,9 +1552,9 @@ async function writeTemplates(vault) {
 }
 
 // src/cli/commands/remove.ts
-import { mkdir as mkdir3, rename as rename3 } from "node:fs/promises";
-import { existsSync as existsSync4 } from "node:fs";
-import { join as join5 } from "node:path";
+import { mkdir as mkdir4, rename as rename3 } from "node:fs/promises";
+import { existsSync as existsSync5 } from "node:fs";
+import { join as join6 } from "node:path";
 var TRASH = ".trash";
 function subtree(vault, root) {
   const ordered = [];
@@ -1221,7 +1574,7 @@ function trashPath(vault, item) {
   const stem = item.stem;
   for (let n = 0; n < 1e3; n++) {
     const name = n === 0 ? `${stem}.md` : `${stem} ${n}.md`;
-    if (!existsSync4(join5(vault.root, TRASH, name))) return `${TRASH}/${name}`;
+    if (!existsSync5(join6(vault.root, TRASH, name))) return `${TRASH}/${name}`;
   }
   return `${TRASH}/${stem} ${Date.now()}.md`;
 }
@@ -1246,8 +1599,8 @@ async function removeItem(vault, ref, options = {}) {
   for (const target of doomed) {
     const trashedTo = trashPath(vault, target);
     if (!dryRun) {
-      await mkdir3(join5(vault.root, TRASH), { recursive: true });
-      await rename3(target.path, join5(vault.root, ...trashedTo.split("/")));
+      await mkdir4(join6(vault.root, TRASH), { recursive: true });
+      await rename3(target.path, join6(vault.root, ...trashedTo.split("/")));
     }
     removed.push({ item: target, trashedTo });
   }
@@ -1296,10 +1649,78 @@ async function archiveItem(vault, ref, undo) {
   return { item, archived, changed: true };
 }
 
+// src/cli/commands/promote.ts
+async function setPromoted(vault, ref, promoted) {
+  const item = vault.resolve(ref);
+  if (isArea(item.area)) {
+    throw new Error(`${item.relPath} is an area and cannot be ${promoted ? "promoted" : "demoted"}.`);
+  }
+  if (item.board === promoted) return { item, promoted, changed: false };
+  await editItem(item, boardEdits(promoted));
+  return { item, promoted, changed: true };
+}
+
+// src/shared/area.ts
+function areaRefusal(item, direction) {
+  if (item.isRoot) return `${item.label} is a root, and a root is not a card or area child.`;
+  if (direction === "card") {
+    if (!item.isArea) return `${item.label} is not an area. Nothing to convert back to a card.`;
+    return null;
+  }
+  if (item.isArea) return `${item.label} is already an area.`;
+  if (item.agent !== void 0 && item.agent.trim() !== "") {
+    return `${item.label} has agent "${item.agent}". Release it before converting it to an area.`;
+  }
+  return null;
+}
+function areaEdits(item, target) {
+  const refusal = areaRefusal(item, target.kind);
+  if (refusal !== null) throw new Error(refusal);
+  if (target.kind === "area") {
+    return [
+      { op: "set", key: "area", value: true },
+      { op: "remove", key: "prev_status" }
+    ];
+  }
+  return [
+    { op: "remove", key: "area" },
+    { op: "remove", key: "prev_status" }
+  ];
+}
+
+// src/cli/commands/area.ts
+async function setArea(vault, ref, options) {
+  const item = vault.resolve(ref);
+  const agent = item.frontmatter.get("agent");
+  const state = {
+    label: item.relPath,
+    isRoot: item.parent === null,
+    isArea: item.area,
+    status: item.status,
+    agent: typeof agent === "string" ? agent : void 0
+  };
+  const direction = options.off ? "card" : "area";
+  const refusal = areaRefusal(state, direction);
+  if (refusal !== null) throw new Error(refusal);
+  if (options.off) {
+    const status = item.status;
+    if (!isStatus(status)) throw new Error(`${item.relPath} has no valid status to preserve.`);
+    const target = { kind: "card" };
+    const edits2 = areaEdits(state, target);
+    const before2 = item.text;
+    const after2 = await editItem(item, edits2);
+    return { item, from: "area", to: "card", status, changed: before2 !== after2 };
+  }
+  const edits = areaEdits(state, { kind: "area" });
+  const before = item.text;
+  const after = await editItem(item, edits);
+  return { item, from: "card", to: "area", status: item.status, changed: before !== after };
+}
+
 // src/cli/commands/hook.ts
 import { execFile } from "node:child_process";
-import { existsSync as existsSync5 } from "node:fs";
-import { chmod, mkdir as mkdir4, readFile as readFile3, rm, writeFile as writeFile3 } from "node:fs/promises";
+import { existsSync as existsSync6 } from "node:fs";
+import { chmod, mkdir as mkdir5, readFile as readFile5, rm as rm2, writeFile as writeFile3 } from "node:fs/promises";
 import { dirname as dirname3, resolve } from "node:path";
 import { promisify } from "node:util";
 var run = promisify(execFile);
@@ -1331,8 +1752,8 @@ exec ${shellQuote(process.execPath)} ${shellQuote(entry)} validate --vault ${she
 async function hookStatus(vault) {
   const git = await gitHook(vault);
   if (!git) return { vault, gitRepo: null, preCommit: "not installed" };
-  const present = existsSync5(git.path);
-  const ours = present && isOurHook(await readFile3(git.path, "utf8"));
+  const present = existsSync6(git.path);
+  const ours = present && isOurHook(await readFile5(git.path, "utf8"));
   return {
     vault,
     gitRepo: git.top,
@@ -1342,28 +1763,28 @@ async function hookStatus(vault) {
 async function installHook(vault, entry, force) {
   const git = await gitHook(vault);
   if (!git) throw new Error(`${vault} is not inside a Git repository. Run: git -C ${shellQuote(vault)} init`);
-  if (existsSync5(git.path)) {
-    const current = await readFile3(git.path, "utf8");
+  if (existsSync6(git.path)) {
+    const current = await readFile5(git.path, "utf8");
     if (!isOurHook(current) && !force) {
       throw new Error(`${git.path} already exists and is not ours. Read it, then pass --force to replace it.`);
     }
   }
-  await mkdir4(dirname3(git.path), { recursive: true });
+  await mkdir5(dirname3(git.path), { recursive: true });
   await writeFile3(git.path, hookBody(vault, entry), "utf8");
   await chmod(git.path, 493);
   return git.path;
 }
 async function uninstallHook(vault) {
   const git = await gitHook(vault);
-  if (!git || !existsSync5(git.path) || !isOurHook(await readFile3(git.path, "utf8"))) return null;
-  await rm(git.path);
+  if (!git || !existsSync6(git.path) || !isOurHook(await readFile5(git.path, "utf8"))) return null;
+  await rm2(git.path);
   return git.path;
 }
 
 // src/cli/commands/setup.ts
-import { cp, lstat, mkdir as mkdir5, readFile as readFile4, rename as rename4, rm as rm2, writeFile as writeFile4 } from "node:fs/promises";
+import { cp, lstat, mkdir as mkdir6, readFile as readFile6, rename as rename4, rm as rm3, writeFile as writeFile4 } from "node:fs/promises";
 import { homedir as homedir2, platform } from "node:os";
-import { dirname as dirname4, join as join6, resolve as resolve2 } from "node:path";
+import { dirname as dirname4, join as join7, resolve as resolve2 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
@@ -1371,11 +1792,11 @@ function detectObsidianRegistryPath(location) {
   if (location.registryPath) return location.registryPath;
   switch (location.platform) {
     case "darwin":
-      return join6(location.home, "Library", "Application Support", "obsidian", "obsidian.json");
+      return join7(location.home, "Library", "Application Support", "obsidian", "obsidian.json");
     case "linux":
-      return join6(location.home, ".config", "obsidian", "obsidian.json");
+      return join7(location.home, ".config", "obsidian", "obsidian.json");
     case "win32":
-      return join6(location.appData ?? join6(location.home, "AppData", "Roaming"), "obsidian", "obsidian.json");
+      return join7(location.appData ?? join7(location.home, "AppData", "Roaming"), "obsidian", "obsidian.json");
     default:
       throw new Error(`wi setup does not know the Obsidian registry location for ${location.platform}.`);
   }
@@ -1387,7 +1808,7 @@ async function readObsidianVaults(location) {
   const path = detectObsidianRegistryPath(location);
   let text;
   try {
-    text = await readFile4(path, "utf8");
+    text = await readFile6(path, "utf8");
   } catch (error) {
     if (isMissingFile2(error)) return [];
     throw error;
@@ -1423,28 +1844,28 @@ async function installSkillCopy(source, destination, force) {
   }
   if (existing?.isSymbolicLink()) return "dev-link";
   if (existing) {
-    const managed = existing.isDirectory() && await readFile4(join6(destination, MANAGED_MARKER), "utf8").then((value) => value === MANAGED_TEXT).catch(() => false);
+    const managed = existing.isDirectory() && await readFile6(join7(destination, MANAGED_MARKER), "utf8").then((value) => value === MANAGED_TEXT).catch(() => false);
     if (!managed && !force) {
       throw new Error(`${destination} already exists and was not installed by wi setup. Read it, then pass --force to replace it.`);
     }
     if (managed) {
-      const same = await readFile4(join6(destination, "SKILL.md"), "utf8").catch(() => null);
-      const expected = await readFile4(join6(source, "SKILL.md"), "utf8");
+      const same = await readFile6(join7(destination, "SKILL.md"), "utf8").catch(() => null);
+      const expected = await readFile6(join7(source, "SKILL.md"), "utf8");
       if (same === expected) return "already-installed";
     }
-    await rm2(destination, { recursive: true, force: true });
+    await rm3(destination, { recursive: true, force: true });
   }
-  await mkdir5(dirname4(destination), { recursive: true });
+  await mkdir6(dirname4(destination), { recursive: true });
   await cp(source, destination, { recursive: true, errorOnExist: true, force: false });
-  await writeFile4(join6(destination, MANAGED_MARKER), MANAGED_TEXT, "utf8");
+  await writeFile4(join7(destination, MANAGED_MARKER), MANAGED_TEXT, "utf8");
   return "installed";
 }
 async function writeDefaultVault(vault) {
   const root = wiConfigDir();
-  const path = join6(root, "config.json");
+  const path = join7(root, "config.json");
   let current = {};
   try {
-    const parsed = JSON.parse(await readFile4(path, "utf8"));
+    const parsed = JSON.parse(await readFile6(path, "utf8"));
     if (!isRecord(parsed)) throw new Error(`cannot update ${path}: expected a JSON object.`);
     current = parsed;
   } catch (error) {
@@ -1456,7 +1877,7 @@ async function writeDefaultVault(vault) {
       throw error;
     }
   }
-  await mkdir5(root, { recursive: true });
+  await mkdir6(root, { recursive: true });
   const temporary = `${path}.tmp-${process.pid}`;
   await writeFile4(temporary, `${JSON.stringify({ ...current, defaultVault: resolve2(vault) }, null, 2)}
 `, "utf8");
@@ -1520,7 +1941,7 @@ async function runSetup(options) {
   let packagedSkill;
   for (const candidate of skillCandidates) {
     try {
-      await readFile4(join6(candidate, "SKILL.md"), "utf8");
+      await readFile6(join7(candidate, "SKILL.md"), "utf8");
       packagedSkill = candidate;
       break;
     } catch (error) {
@@ -1529,8 +1950,8 @@ async function runSetup(options) {
   }
   if (!packagedSkill) throw new Error("the recursive-board skill is missing from this installation.");
   const destinations = [
-    join6(home, ".claude", "skills", "recursive-board"),
-    join6(home, ".agents", "skills", "recursive-board")
+    join7(home, ".claude", "skills", "recursive-board"),
+    join7(home, ".agents", "skills", "recursive-board")
   ];
   const outcomes = await Promise.all(destinations.map((destination) => installSkillCopy(packagedSkill, destination, options.force)));
   const configPath = await writeDefaultVault(vault);
@@ -1557,15 +1978,23 @@ var HELP = `wi \u2014 the Recursive Board CLI
 Usage
   wi setup [--yes] [--vault <path>] [--force]
   wi new <title> [--parent <ref>] [--status <s>] [--template <t>] [--owner <o>] [--agent <a>]
-                                [--priority <n>]
+                 [--priority <n>] [--objective <text>] [--context <text>]... [--criteria <text>]...
+                 [--strict]
   wi status <ref> <status>
+  wi note <ref> <text> [--agent <name>]
+  wi area <ref> [--off]
   wi claim <ref> --agent <name>
+  wi agents
   wi release <ref> --reason <text> [--where <branch-or-path>]
   wi move <ref> --to <ref>
   wi archive <ref> [--undo]
+  wi promote <ref>
+  wi demote <ref>
   wi rm <ref> [--recursive] [--dry-run]
   wi children [<ref>] [--status <s>] [--tree] [--archived]
   wi validate
+  wi retag [--dry-run]
+  wi graph
   wi template [list|write]
   wi hook <install|uninstall|status> [--force]
   wi here [--board <ref>] [--vault <path>]
@@ -1584,6 +2013,19 @@ Options
   -V, --version    Print the version.
 
 Notes
+  \`wi new\` writes the brief: --objective once, --context and --criteria once per paragraph or
+  criterion. It warns when the card has no Objective or Acceptance Criteria; --strict refuses it.
+  A title's unsafe filename characters become hyphens. When another item has the same filename,
+  the new file gets the id's suffix; wi never writes over a file.
+  \`wi new\` makes a parent a board when it gives the parent its first child. Set
+  "autoPromote": false in .wi.json to turn this off. A root or an area is never changed.
+  With "areaTags": true in .wi.json, each work item carries one tag naming its areas, such as
+  area/work/website. \`wi new\` writes it. After \`wi move\` or \`wi area\`, run \`wi retag\` to fix
+  the tags below. \`wi graph\` writes a colour group per area to .obsidian/graph.json and keeps
+  your own groups. Close the graph view first: Obsidian may write over the file.
+  \`wi note\` appends "- <date> <time>, <agent>: <text>" under Notes. The agent defaults to the
+  card's agent. The write re-reads the card under a lock, so two notes at once both survive.
+  \`wi status <ref> done\` says when that was the parent's last open child. It does not close the parent.
   Unticking a done item is \`wi status <ref> <its prev_status>\`, which also clears the record.
   \`wi validate\` exits 1 when the vault has errors, so it works as a pre-commit hook.
   \`wi template write\` regenerates Templates/ from the code, which is authoritative.
@@ -1594,10 +2036,18 @@ Notes
   folder, because the index cannot read it and may be missing a work item. Let the sync
   client download the file, or delete the stray file, then retry. There is no --force.
   \`wi archive\` changes one flag. Descendants disappear with their parent at read time.
+  \`wi area <ref>\` marks a card as an area and keeps its status. It refuses a card with an agent.
+  Use \`wi area <ref> --off\` to convert back without changing its status.
+  \`wi claim\` refuses a card with blocked: true, and \`wi children\` marks one [blocked].
+  \`wi claim\` lets an agent hold a card and its subtasks at once. It refuses a board with a child in
+  doing that a different agent or a person works.
+  \`wi agents\` reports the advisory limit, the number of distinct agents with a doing card, and each
+  claimed doing card. WI_MAX_AGENTS overrides
+  maxAgents from .wi.json for one run. Dispatchers decide whether to wait; wi claim does not enforce it.
   \`wi new\` warns when such a file exists because a new id or filename may clash with it.
   \`wi here\` reads or sets this repository's vault and board pointer in your user config.
 `;
-var VERSION = "0.2.0";
+var VERSION = "0.3.0";
 var UsageError = class extends Error {
 };
 async function main(argv) {
@@ -1615,11 +2065,16 @@ async function main(argv) {
       where: { type: "string" },
       priority: { type: "string" },
       template: { type: "string" },
+      objective: { type: "string" },
+      context: { type: "string", multiple: true },
+      criteria: { type: "string", multiple: true },
+      strict: { type: "boolean", default: false },
       vault: { type: "string" },
       board: { type: "string" },
       tree: { type: "boolean", default: false },
       archived: { type: "boolean", default: false },
       undo: { type: "boolean", default: false },
+      off: { type: "boolean", default: false },
       recursive: { type: "boolean", short: "r", default: false },
       "dry-run": { type: "boolean", default: false },
       json: { type: "boolean", default: false },
@@ -1643,6 +2098,10 @@ async function main(argv) {
     throw new UsageError("--force applies only to wi hook install or wi setup.");
   }
   if (values.yes && command !== "setup") throw new UsageError("--yes applies only to wi setup.");
+  if (values.off && command !== "area") throw new UsageError("--off applies only to wi area.");
+  if ((values.objective !== void 0 || values.context !== void 0 || values.criteria !== void 0 || values.strict) && command !== "new") {
+    throw new UsageError("--objective, --context, --criteria and --strict apply only to wi new.");
+  }
   if (command === "setup") {
     if (rest.length > 0) throw new UsageError("wi setup takes options only. Run wi setup --help for usage.");
     await runSetup({
@@ -1660,14 +2119,24 @@ async function main(argv) {
       return runNew(vault, rest, values, json);
     case "status":
       return runStatus(vault, rest, json);
+    case "area":
+      return withRetagHint(vault, () => runArea(vault, rest, values, json));
+    case "note":
+      return runNote(vault, rest, values, json);
     case "claim":
       return runClaim(vault, rest, values, json);
+    case "agents":
+      return runAgents(vault, rest, json);
     case "release":
       return runRelease(vault, rest, values, json);
     case "move":
-      return runMove(vault, rest, values, json);
+      return withRetagHint(vault, () => runMove(vault, rest, values, json));
     case "archive":
       return runArchive(vault, rest, values, json);
+    case "promote":
+      return runPromote(vault, rest, true, json);
+    case "demote":
+      return runPromote(vault, rest, false, json);
     case "rm":
       return runRemove(vault, rest, values, json);
     case "children":
@@ -1679,6 +2148,10 @@ async function main(argv) {
       return runChildren(vault, rest, values, json);
     case "validate":
       return runValidate(vault, json);
+    case "retag":
+      return runRetag(vault, rest, values, json);
+    case "graph":
+      return runGraph(vault, rest, json);
     case "template":
       return runTemplate(vault, rest, json);
     case "hook":
@@ -1758,7 +2231,13 @@ async function runNew(vault, rest, values, json) {
     ...typeof values["owner"] === "string" ? { owner: values["owner"] } : {},
     ...typeof values["agent"] === "string" ? { agent: values["agent"] } : {},
     ...typeof values["template"] === "string" ? { template: values["template"] } : {},
-    ...priority !== void 0 ? { priority } : {}
+    ...priority !== void 0 ? { priority } : {},
+    brief: {
+      objective: typeof values["objective"] === "string" ? values["objective"] : void 0,
+      context: Array.isArray(values["context"]) ? values["context"] : void 0,
+      criteria: Array.isArray(values["criteria"]) ? values["criteria"] : void 0
+    },
+    strict: values["strict"] === true
   });
   if (vault.unaccounted.length > 0) {
     process.stderr.write(
@@ -1766,9 +2245,28 @@ async function runNew(vault, rest, values, json) {
 `
     );
   }
-  if (json) print({ id: created.id, path: created.relPath, parent: created.parentStem });
-  else process.stdout.write(`${created.id}  ${created.relPath}  (child of ${created.parentStem})
+  if (created.gaps.length > 0) {
+    process.stderr.write(`wi: warning: ${created.id} has no ${created.gaps.join(" or ")}. Pass --objective and --criteria, or fill the card before work starts.
+`);
+  }
+  if (created.renamed) {
+    process.stderr.write(`wi: note: another item has this filename, so this one is ${created.relPath}. If they are different work, give the card a more specific title.
+`);
+  }
+  if (json) {
+    print({
+      id: created.id,
+      path: created.relPath,
+      parent: created.parentStem,
+      promoted_parent: created.promotedParent,
+      gaps: created.gaps
+    });
+  } else {
+    process.stdout.write(`${created.id}  ${created.relPath}  (child of ${created.parentStem})
+`);
+    if (created.promotedParent) process.stdout.write(`${created.parentStem}  promoted to a board (its first child)
 `);
+  }
   return 0;
 }
 async function runStatus(vault, rest, json) {
@@ -1784,7 +2282,8 @@ async function runStatus(vault, rest, json) {
       from: change.from ?? null,
       to: change.to,
       prev_status: change.recorded ?? null,
-      changed: change.changed
+      changed: change.changed,
+      parent_ready: change.parentReady?.id ?? null
     });
   } else if (!change.changed) {
     process.stdout.write(`${label(change.item)} is already ${change.to}. Nothing written.
@@ -1792,6 +2291,35 @@ async function runStatus(vault, rest, json) {
   } else {
     const recorded = change.recorded ? `  (prev_status: ${change.recorded})` : "";
     process.stdout.write(`${label(change.item)}  ${change.from ?? "\u2014"} \u2192 ${change.to}${recorded}
+`);
+  }
+  const ready = change.parentReady;
+  if (ready && !json) {
+    process.stdout.write(`${label(ready)}  every child is done. If its own criteria are met, run: wi status ${ready.id ?? ready.stem} done
+`);
+  }
+  return 0;
+}
+async function runArea(vault, rest, values, json) {
+  const ref = rest.join(" ").trim();
+  if (ref === "") {
+    throw new UsageError("wi area needs a <ref>. Use --off to convert an area back to a card.");
+  }
+  if (typeof values["status"] === "string") throw new UsageError("--status does not apply to wi area; conversion preserves the current status.");
+  const change = await setArea(vault, ref, {
+    off: values["off"] === true
+  });
+  if (json) {
+    print({
+      id: change.item.id,
+      path: change.item.relPath,
+      from: change.from,
+      to: change.to,
+      status: change.status ?? null,
+      changed: change.changed
+    });
+  } else {
+    process.stdout.write(`${label(change.item)}  ${change.from} \u2192 ${change.to}${change.status ? `  (status: ${change.status})` : ""}
 `);
   }
   return 0;
@@ -1808,6 +2336,8 @@ async function runClaim(vault, rest, values, json) {
   const ref = rest.join(" ").trim();
   if (ref === "") throw new UsageError("wi claim needs a <ref> and --agent <name>.");
   const agent = singleLineOption(values, "agent");
+  const maxAgents = maxAgentsForRun(vault);
+  const active = activeAgentNames(vault);
   const change = await claimItem(vault, ref, agent);
   if (json) print({
     id: change.item.id,
@@ -1819,6 +2349,53 @@ async function runClaim(vault, rest, values, json) {
   });
   else process.stdout.write(change.changed ? `${label(change.item)}  ${change.from ?? "\u2014"} \u2192 doing  (agent: ${agent})
 ` : `${label(change.item)} is already claimed by ${agent} in doing. Nothing written.
+`);
+  if (change.changed && maxAgents !== null && !active.has(agent) && active.size + 1 > maxAgents) {
+    process.stderr.write(`wi: warning: agent limit is ${maxAgents}; ${active.size + 1} agents now have a doing card.
+`);
+  }
+  return 0;
+}
+async function runNote(vault, rest, values, json) {
+  const [ref, ...words] = rest;
+  const text = words.join(" ").trim();
+  if (ref === void 0 || text === "") {
+    throw new UsageError('wi note needs a <ref> and the text. Try: wi note wi-a7f3 "Priced 12 lines."');
+  }
+  const agent = values["agent"] === void 0 ? void 0 : singleLineOption(values, "agent");
+  const added = await addNote(vault, ref, text, agent);
+  if (json) print({ id: added.item.id, path: added.item.relPath, line: added.line });
+  else process.stdout.write(`${label(added.item)}  ${added.line}
+`);
+  return 0;
+}
+function claimedDoing(vault) {
+  return vault.items.flatMap((item) => {
+    const agent = item.frontmatter.get("agent");
+    return item.status === "doing" && typeof agent === "string" && agent.trim() !== "" ? [{ agent, item }] : [];
+  });
+}
+function activeAgentNames(vault) {
+  return new Set(claimedDoing(vault).map((claim) => claim.agent));
+}
+function runAgents(vault, rest, json) {
+  if (rest.length > 0) throw new UsageError("wi agents takes no arguments.");
+  const maxAgents = maxAgentsForRun(vault);
+  const claims = claimedDoing(vault).sort((a, b) => a.agent.localeCompare(b.agent));
+  const activeAgents = new Set(claims.map((claim) => claim.agent)).size;
+  if (json) {
+    print({ maxAgents, activeAgents, claims: claims.map(({ agent, item }) => ({
+      agent,
+      id: item.id ?? null,
+      title: item.title ?? item.stem,
+      path: item.relPath
+    })) });
+    return 0;
+  }
+  process.stdout.write(`limit  ${maxAgents === null ? "none" : maxAgents}
+agents with a doing card  ${activeAgents}
+`);
+  for (const { agent, item } of claims) process.stdout.write(`  ${agent}  ${label(item)}
 `);
   return 0;
 }
@@ -1879,6 +2456,19 @@ async function runArchive(vault, rest, values, json) {
   }
   return 0;
 }
+async function runPromote(vault, rest, promoted, json) {
+  const ref = rest.join(" ").trim();
+  if (ref === "") throw new UsageError(`wi ${promoted ? "promote" : "demote"} needs a <ref>.`);
+  const change = await setPromoted(vault, ref, promoted);
+  if (json) {
+    print({ id: change.item.id, path: change.item.relPath, promoted: change.promoted, changed: change.changed });
+  } else {
+    const verb = promoted ? "promoted" : "demoted";
+    process.stdout.write(`${label(change.item)}  ${change.changed ? verb : `already ${promoted ? "a board" : "a card"}; nothing written`}
+`);
+  }
+  return 0;
+}
 async function runRemove(vault, rest, values, json) {
   const ref = rest.join(" ").trim();
   if (ref === "") throw new UsageError("wi rm needs a <ref>.");
@@ -1936,7 +2526,8 @@ function runChildren(vault, rest, values, json) {
         status: row.item.status ?? null,
         children: row.childCount,
         depth: row.depth,
-        archived: row.archived
+        archived: row.archived,
+        blocked: row.item.frontmatter.get("blocked") === true
       }))
     });
     return 0;
@@ -1963,6 +2554,39 @@ function runChildren(vault, rest, values, json) {
 `);
   return 0;
 }
+async function withRetagHint(vault, run2) {
+  const code = await run2();
+  if (vault.config.areaTags) {
+    const stale = staleAreaTags(await loadVault(vault.root)).length;
+    if (stale > 0) process.stderr.write(`wi: ${stale} work item${stale === 1 ? " has" : "s have"} a stale area tag. Run wi retag.
+`);
+  }
+  return code;
+}
+async function runRetag(vault, rest, values, json) {
+  if (rest.length > 0) throw new UsageError("wi retag takes no arguments.");
+  const dryRun = values["dry-run"] === true;
+  const changed = await retag(vault, dryRun);
+  if (json) {
+    print({ dryRun, changed: changed.map(({ item, from, to }) => ({ id: item.id ?? null, path: item.relPath, from, to })) });
+    return 0;
+  }
+  const verb = dryRun ? "would retag" : "retagged";
+  for (const { item, to } of changed) process.stdout.write(`${verb}  ${label(item)}  [${to.join(", ")}]
+`);
+  process.stdout.write(`${changed.length} work item${changed.length === 1 ? "" : "s"}${dryRun ? ", nothing written" : ""}
+`);
+  return 0;
+}
+async function runGraph(vault, rest, json) {
+  if (rest.length > 0) throw new UsageError("wi graph takes no arguments.");
+  const written = await writeGraphColours(vault);
+  if (json) print(written);
+  else process.stdout.write(`wrote ${written.groups} area colour groups to ${written.path}, kept ${written.kept} of your own
+reopen the graph view to see them
+`);
+  return 0;
+}
 async function runValidate(vault, json) {
   const report = await validate(vault);
   if (json) {
@@ -2073,7 +2697,8 @@ function row3(row) {
   const kids = row.childCount > 0 ? `  (${row.childCount})` : "";
   const board = row.item.board ? "  [board]" : "";
   const archived = row.archived ? "  [archived]" : "";
-  return `${row.item.id ?? "(no id)"}  ${status.padEnd(7)}  ${row.item.title ?? row.item.stem}${kids}${board}${archived}`;
+  const blocked = row.item.frontmatter.get("blocked") === true ? "  [blocked]" : "";
+  return `${row.item.id ?? "(no id)"}  ${status.padEnd(7)}  ${row.item.title ?? row.item.stem}${kids}${board}${blocked}${archived}`;
 }
 function print(value) {
   process.stdout.write(`${JSON.stringify(value, null, 2)}