gcf-aif-ext 0.3.0 → 0.4.1

package/lib/unit-ops.js

@@ -1,12 +1,12 @@
-// The moves a design unit makes out of design/ (GCF-PRD §4): `take` into a card, `done` into
-// tests and code, `drop` into the graveyard. Each one removes the section and its backlog line
-// in the same step, so an id never lives in two places (M12).
-import { readFile, unlink } from 'node:fs/promises';
+// The moves a design unit makes out of design/ (Methodology §2): `take` into a work item, `done`
+// straight into tests and code, `drop` into the graveyard. Each one removes the section and its
+// backlog line in the same step, so an id never lives in two places (M12).
+import { readFile } from 'node:fs/promises';
 import { existsSync, readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import { serialize } from './frontmatter.js';
-import { CARD_TYPES, listOf } from './design.js';
+import { CARD_TYPES, SLUG_RE, listOf } from './design.js';
 import { buildLedger } from './ledger.js';
 import { designCheck } from './design-check.js';
 import { atomicWrite, withFileRollback } from './safe-path.js';
@@ -14,10 +14,13 @@ import { writeIndex } from './index-gen.js';
 import { operationInProgress, commitPaths } from './git.js';
 import { upsertBlock, openSystemDoc } from './systems-doc.js';
 import { buryLine, recordLine } from './verdict-fs.js';
+import { DEFAULT_GATE } from './validate-item.js';
 
 /** A design file's text without the `## <id>` section. */
 export function removeUnit(text, id) {
-  const lines = String(text).split('\n');
+  // A file kept with CRLF stays CRLF: work in LF, write back in the file's own line ending.
+  const eol = String(text).match(/\r?\n/)?.[0] ?? '\n';
+  const lines = String(text).replace(/\r\n/g, '\n').split('\n');
   const at = lines.findIndex((l) => l.trimEnd() === `## ${id}`);
   if (at < 0) return text;
   let end = lines.findIndex((l, i) => i > at && /^## \S/.test(l));
@@ -26,7 +29,7 @@ export function removeUnit(text, id) {
   return `${[...lines.slice(0, at), ...lines.slice(end)]
     .join('\n')
     .replace(/\n{3,}/g, '\n\n')
-    .trimEnd()}\n`;
+    .trimEnd()}\n`.replace(/\n/g, eol);
 }
 
 /** backlog.md without the line of `id`. */
@@ -37,19 +40,20 @@ export const backlogWithout = (text, id) =>
     .join('\n');
 
 /** The single design unit `id`, or an error naming where the id lives instead. */
-async function designUnit(projectDir, id) {
-  const ledger = await buildLedger(projectDir);
+function designUnitOf(ledger, id) {
   const { live, terminal } = ledger.where(id);
   if (live.length !== 1 || live[0].state !== 'design') {
     const at = live.map((p) => p.file).join(', ') || terminal.join(', ') || 'nowhere';
     throw new Error(`${id} is not a single unit of gcf/design/ (it is: ${at})`);
   }
 
-  const unit = ledger.design.flatMap((d) => d.units).find((u) => u.id === id);
-
-  return /** @type {import('./design.js').Unit} */ (unit);
+  return /** @type {import('./design.js').Unit} */ (
+    ledger.design.flatMap((d) => d.units).find((u) => u.id === id)
+  );
 }
 
+const designUnit = async (projectDir, id) => designUnitOf(await buildLedger(projectDir), id);
+
 /** Files a move rewrites: the design file, the backlog, then whatever the move adds. */
 function basePaths(root, unit) {
   return { design: path.join(root, unit.file), backlog: path.join(root, 'backlog.md') };
@@ -61,67 +65,119 @@ async function cutUnit(paths, id) {
     await atomicWrite(paths.backlog, backlogWithout(await readFile(paths.backlog, 'utf8'), id));
 }
 
-/** The frontmatter a card starts with: the unit's header plus the fields of the card stage. */
-function cardData(unit, today) {
+/** The frontmatter a work item starts with: the unit's header plus the fields of work. */
+function unitItemData(unit, today, parent) {
   const h = unit.header;
   const pillars = listOf(h.pillars);
+  const gate = DEFAULT_GATE[h.type];
 
   return {
-    schema: 2,
+    schema: 3,
     id: unit.id,
     type: h.type,
+    gate,
     ...(h.title ? { title: h.title } : {}),
-    status: 'proposed',
+    status: 'ready',
+    ...(parent ? { parent } : {}),
     system: listOf(h.system),
     depends: listOf(h.depends),
     pillars: pillars === 'TBD' ? [] : pillars,
     source: h.source,
     ...(h.reopens ? { reopens: h.reopens } : {}),
-    tune_count: 0,
-    built_at: null,
+    ...(SLUG_RE.test(h.milestone ?? '') && h.milestone !== 'later'
+      ? { milestone: h.milestone }
+      : {}),
+    ...(gate === 'verdict' ? { tune_count: 0 } : {}),
+    // A child's capability is its feature's: the feature writes the one LIVE.md record.
+    ...(parent ? { live: { none: 'parent' } } : {}),
     created: today,
   };
 }
 
+/** The feature `id` to group the taken units under: the live one, or a new one. */
+function featureFor(ledger, root, { id, unitIds, systems, today }) {
+  const file = path.join(root, 'work', `${id}.md`);
+  const live = ledger.item(id);
+  if (live) {
+    if (live.data.type !== 'feature')
+      throw new Error(`${id} is a ${live.data.type}, not a feature`);
+    const children = [...new Set([...(live.data.children ?? []), ...unitIds])];
+
+    return { file, text: serialize({ ...live.data, children }, live.body) };
+  }
+
+  if (ledger.known(id)) throw new Error(`${id} is taken already: ids are never reused`);
+  const data = {
+    schema: 3,
+    id,
+    type: 'feature',
+    gate: 'auto',
+    status: 'ready',
+    children: unitIds,
+    system: [...new Set(systems)],
+    depends: [],
+    created: today,
+  };
+
+  return { file, text: serialize(data, `\nintent:\n- TBD: what ${id} gives the player\n`) };
+}
+
+/** A unit goes into work only ready: no TBD, no blocking D1, no blocking finding. */
+function refuseUnready(units, summaries) {
+  for (const unit of units) {
+    const summary = summaries.find((u) => u.id === unit.id);
+    if (summary?.ready) continue;
+    const why = summary?.blocked_by.length
+      ? `blocked by ${summary.blocked_by.join(', ')}`
+      : `${summary?.tbd ?? '?'} TBD${summary?.pillars_owed ? ', pillars among them' : ''} ` +
+        'or a blocking design-check finding';
+    throw new Error(`${unit.id} is not ready (${why}): answer it in design/ first`);
+  }
+}
+
 /**
- * Take a ready soft unit into work: its section becomes cards/<id>.md with the same body.
- * No commit — `/gcf-card` adds `contract` and `interactions`, and the pre-commit gate holds
- * the card until it carries both.
+ * Take ready design units into work: each section becomes gcf/work/<id>.md with the same body.
+ * One unit stands alone; `feature` groups them under a feature item, new or live. No commit —
+ * `/gcf-card` adds `contract` and `interactions`, and the pre-commit gate holds the item until
+ * it carries both.
  */
-export async function takeUnit(
+export async function takeUnits(
   projectDir,
-  id,
-  { today = new Date().toISOString().slice(0, 10) } = {},
+  ids,
+  { feature = null, today = new Date().toISOString().slice(0, 10) } = {},
 ) {
   const root = path.join(path.resolve(projectDir), 'gcf');
-  const unit = await designUnit(projectDir, id);
-  if (!CARD_TYPES.includes(unit.header.type)) {
-    throw new Error(
-      `${id} is hard: close its TBD in place, run the AIF cycle, then gcf done ${id}`,
-    );
-  }
-
-  const summary = (await designCheck(projectDir)).units.find((u) => u.id === id);
-  if (!summary?.ready) {
-    const why = summary?.blocked_by.length
-      ? `blocked by ${summary.blocked_by.join(', ')}`
-      : `${summary?.tbd ?? '?'} TBD or a blocking design-check finding`;
-    throw new Error(`${id} is not ready (${why}): answer it in design/ first`);
+  const ledger = await buildLedger(projectDir);
+  const units = ids.map((id) => designUnitOf(ledger, id));
+  refuseUnready(units, (await designCheck(projectDir)).units);
+  const writes = units.map((unit) => ({
+    file: path.join(root, 'work', `${unit.id}.md`),
+    text: serialize(unitItemData(unit, today, feature), `\n${unit.body.trim()}\n`),
+  }));
+  for (const w of writes)
+    if (existsSync(w.file)) throw new Error(`gcf/work/${path.basename(w.file)} already exists`);
+  if (feature) {
+    const systems = units.flatMap((u) => listOf(u.header.system)).filter((s) => s !== 'TBD');
+    writes.push(featureFor(ledger, root, { id: feature, unitIds: ids, systems, today }));
   }
 
-  const paths = { ...basePaths(root, unit), card: path.join(root, 'cards', `${id}.md`) };
-  if (existsSync(paths.card)) throw new Error(`gcf/cards/${id}.md already exists`);
-  await withFileRollback([...Object.values(paths), path.join(root, 'INDEX.md')], async () => {
-    await atomicWrite(paths.card, serialize(cardData(unit, today), `\n${unit.body.trim()}\n`));
-    await cutUnit(paths, id);
+  const paths = units.map((u) => basePaths(root, u));
+  const touched = [
+    ...writes.map((w) => w.file),
+    ...paths.flatMap((p) => [p.design, p.backlog]),
+    path.join(root, 'INDEX.md'),
+  ];
+  await withFileRollback(touched, async () => {
+    for (const w of writes) await atomicWrite(w.file, w.text);
+    for (const [i, unit] of units.entries()) await cutUnit(paths[i], unit.id);
     await writeIndex(root);
   });
 
-  return { card: `gcf/cards/${id}.md` };
+  return { items: writes.map((w) => `gcf/work/${path.basename(w.file)}`) };
 }
 
 /** A file's text at a git revision spec (`HEAD:./x`, `:./x` for the index), '' when absent. */
-function gitText(projectDir, spec) {
+export function gitText(projectDir, spec) {
   const res = spawnSync('git', ['show', spec], { cwd: projectDir, encoding: 'utf8' });
 
   return res.status === 0 ? res.stdout : '';
@@ -144,12 +200,18 @@ function uncommitted(projectDir, file) {
  * Run a move that ends with its fixed-format commit, all of it or none of it. The commit takes
  * whole files and deletes the unit's section, so any uncommitted edit in them refuses the move
  * up front — an answer in the unit itself included: it would leave in a commit that never held
- * it, and no history would keep it.
+ * it, and no history would keep it. `inputs` are the item files the move reads and rewrites:
+ * their own uncommitted edits (an answer, a live: delta) ride along on purpose.
+ * @param {string} projectDir
+ * @param {string} message
+ * @param {{files: string[], mutate: () => Promise<void>, commit: boolean, inputs?: string[]}} move
  */
-async function commitMove(projectDir, message, { files, mutate, commit }) {
+export async function commitMove(projectDir, message, { files, mutate, commit, inputs = [] }) {
   const busy = commit ? operationInProgress(projectDir) : null;
   if (busy) throw new Error(`cannot record ${message} while ${busy} is in progress`);
-  const dirty = commit ? files.filter((f) => uncommitted(projectDir, f)) : [];
+  const dirty = commit
+    ? files.filter((f) => !inputs.includes(f) && uncommitted(projectDir, f))
+    : [];
   if (dirty.length) {
     const names = dirty.map((f) => path.relative(projectDir, f)).join(', ');
     throw new Error(
@@ -176,14 +238,14 @@ async function commitMove(projectDir, message, { files, mutate, commit }) {
 }
 
 /**
- * A hard unit is built and its tests are green: it leaves design/. A line every future reader
- * of the subsystem must remember goes to the systems doc's `constraints:` (GCF-PRD §6.3).
+ * A hard unit is built and its tests are green: it leaves design/ without a work item. A line
+ * every future reader of the subsystem must remember goes to the systems doc's `constraints:`.
  */
 export async function doneUnit(projectDir, id, { constraints = [], commit = true } = {}) {
   const root = path.join(path.resolve(projectDir), 'gcf');
   const unit = await designUnit(projectDir, id);
   if (CARD_TYPES.includes(unit.header.type))
-    throw new Error(`${id} is soft: it leaves design/ through a card and a verdict`);
+    throw new Error(`${id} is soft: it leaves design/ through a work item and a verdict`);
   const summary = (await designCheck(projectDir)).units.find((u) => u.id === id);
   if (summary?.tbd)
     throw new Error(`${id} still carries ${summary.tbd} TBD: it was built on a hole — answer it`);
@@ -194,13 +256,7 @@ export async function doneUnit(projectDir, id, { constraints = [], commit = true
   const mutate = async () => {
     await cutUnit(paths, id);
     await recordLine(root, id, 'done');
-    if (!doc) return;
-    const body = upsertBlock(
-      doc.body,
-      'constraints',
-      constraints.map((c) => `- ${c}`),
-    );
-    await atomicWrite(doc.file, serialize({ ...doc.data, updated_by: id }, body));
+    if (doc) await addConstraints(doc, id, constraints);
   };
 
   return {
@@ -209,57 +265,29 @@ export async function doneUnit(projectDir, id, { constraints = [], commit = true
   };
 }
 
-/**
- * A card taken into work but never built is given up: no playtest, so no verdict — a drop. Its
- * file goes, the graveyard keeps the reason. A built card waits for its verdict instead.
- */
-async function dropCard(projectDir, card, { reason, tags, commit }) {
-  const root = path.join(path.resolve(projectDir), 'gcf');
-  const id = String(card.data.id);
-  if (!['proposed', 'tuning'].includes(card.data.status))
-    throw new Error(`${id} is ${card.data.status}: play it and give the verdict, kill included`);
-  const rel = `./${path.relative(projectDir, card.file).replaceAll('\\', '/')}`;
-  if (commit && !gitText(projectDir, `HEAD:${rel}`)) {
-    throw new Error(
-      `${id} was taken but its card is not committed: commit it first, or undo the take ` +
-        `(delete the card, restore its section in gcf/design/ and its backlog line)`,
-    );
-  }
-
-  const files = [card.file, path.join(root, 'graveyard.md')];
-  const mutate = async () => {
-    await buryLine(root, id, reason, tags.length ? tags : (card.data.system ?? []));
-    await unlink(card.file);
-  };
-
-  return {
-    id,
-    hash: await commitMove(projectDir, `gcf(drop): ${id}`, { files, mutate, commit }),
-  };
+/** Lines every reader of a subsystem must remember, into its systems doc's `constraints:`. */
+export async function addConstraints(doc, id, constraints) {
+  const body = upsertBlock(
+    doc.body,
+    'constraints',
+    constraints.map((c) => `- ${c}`),
+  );
+  await atomicWrite(doc.file, serialize({ ...doc.data, updated_by: id }, body));
 }
 
-/**
- * A unit — or a card not yet built — is dropped before any playtest: a graveyard line keeps the
- * reason (GCF-PRD §5.6).
- */
+/** A unit is dropped before any work: a graveyard line keeps the reason (Methodology §9). */
 export async function dropUnit(projectDir, id, { reason, tags = [], commit = true }) {
   if (!String(reason ?? '').trim())
     throw new Error('a drop needs a reason: the graveyard keeps it');
-  const ledger = await buildLedger(projectDir);
-  const live = ledger.where(id).live;
-  if (live.length === 1 && live[0].state === 'card') {
-    const card = ledger.cards.find((c) => c.data.id === id);
-
-    return dropCard(projectDir, card, { reason, tags, commit });
-  }
-
   const root = path.join(path.resolve(projectDir), 'gcf');
   const unit = await designUnit(projectDir, id);
   const paths = basePaths(root, unit);
   const system = listOf(unit.header.system);
   const files = [paths.design, paths.backlog, path.join(root, 'graveyard.md')];
+  const type = unit.header.type ?? 'mechanic';
   const mutate = async () => {
-    await buryLine(root, id, reason, tags.length ? tags : system === 'TBD' ? [] : system);
+    const lineTags = tags.length ? tags : system === 'TBD' ? [] : system;
+    await buryLine(root, id, { type, reason, tags: lineTags });
     await cutUnit(paths, id);
   };
 

package/lib/validate-item.js

@@ -0,0 +1,244 @@
+// Runtime mirror of schemas/item.schema.json for the pre-commit hook (no ajv in production
+// deps). `validateFields` is the per-field part the parity test holds against the schema; the
+// cross-field rules (which status goes with which gate or type) live only here.
+import { STORED } from './transitions.js';
+
+export const ITEM_TYPES = [
+  'feature',
+  'mechanic',
+  'resource',
+  'rule',
+  'constraint',
+  'entity',
+  'tech',
+  'bug',
+  'spike',
+  'asset',
+  'content',
+  'perf',
+  'release',
+];
+// A work item that carries a design unit's body: checked against the unit's profile.
+export const UNIT_ITEM_TYPES = ['mechanic', 'resource', 'rule', 'constraint', 'entity'];
+// Methodology §3.1: who closes an item by default; the operator flips it per item.
+export const DEFAULT_GATE = {
+  feature: 'auto',
+  mechanic: 'verdict',
+  resource: 'verdict',
+  rule: 'auto',
+  constraint: 'auto',
+  entity: 'auto',
+  tech: 'auto',
+  bug: 'auto',
+  spike: 'decision',
+  asset: 'verdict',
+  content: 'auto',
+  perf: 'auto',
+  release: 'decision',
+};
+export const GATES = ['verdict', 'auto', 'decision'];
+export const SEVERITIES = ['critical', 'high', 'medium', 'low'];
+const CHANGES = ['added', 'modified', 'removed'];
+
+const FIELDS = [
+  'schema',
+  'id',
+  'type',
+  'gate',
+  'title',
+  'status',
+  'parent',
+  'children',
+  'system',
+  'depends',
+  'pillars',
+  'source',
+  'reopens',
+  'milestone',
+  'parallel',
+  'plan',
+  'tune_count',
+  'severity',
+  'blocked',
+  'since',
+  'frozen',
+  'live',
+  'model',
+  'effort',
+  'created',
+];
+const REQUIRED = ['schema', 'id', 'type', 'gate', 'status', 'created'];
+const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+// YAML reads `id: 2024` as a number; RegExp.test would pass it and every string lookup miss it.
+const isSlug = (v) => typeof v === 'string' && SLUG.test(v);
+const slugList = (v) => Array.isArray(v) && v.every(isSlug);
+const isText = (v) => typeof v === 'string' && v.trim().length > 0;
+const nullable = (check) => (v) => v === null || v === undefined || check(v);
+const LIVE_SHAPE = 'live must be {none: <why>} or {changes: [...]} with at least one change';
+
+/** At most two sentences and 250 characters: a table of contents, not a description. */
+export function summaryProblem(s) {
+  if (!isText(s)) return 'summary must be text';
+  if (s.length > 250) return `summary is ${s.length} characters, at most 250`;
+  if ((s.match(/[.!?](\s|$)/g) ?? []).length > 2) return 'summary is more than two sentences';
+
+  return null;
+}
+
+/** One `changes:` entry of a live: delta, or null when it is well formed. */
+function changeProblem(c) {
+  if (typeof c !== 'object' || c === null) return 'each live change is {id, change, summary}';
+  const extra = Object.keys(c).find((k) => !['id', 'change', 'summary', 'refs'].includes(k));
+  if (extra) return `unknown live change field: ${extra}`;
+  if (!isSlug(c.id)) return 'a live change id must be a lowercase hyphen slug';
+  if (!CHANGES.includes(c.change)) return `live change must be ${CHANGES.join(' | ')}`;
+  if (c.change !== 'removed' && !isText(c.summary)) return `live change ${c.id} needs a summary`;
+  const bad = c.summary === undefined ? null : summaryProblem(c.summary);
+  if (bad) return `live change ${c.id}: ${bad}`;
+
+  return c.refs === undefined || isText(c.refs) ? null : `live change ${c.id}: refs must be text`;
+}
+
+/** A live: delta (Methodology §8): `{none: <why>}` or `{changes: [{id, change, summary}]}`. */
+export function liveProblem(v) {
+  if (v === null || v === undefined) return null;
+  if (typeof v !== 'object' || Array.isArray(v)) return LIVE_SHAPE;
+  const [key, ...more] = Object.keys(v);
+  if (more.length) return LIVE_SHAPE;
+  if (key === 'none')
+    return isText(v.none) ? null : 'live.none must say why the item changes no capability';
+  const changes = key === 'changes' ? v.changes : null;
+  if (!Array.isArray(changes) || !changes.length) return LIVE_SHAPE;
+
+  return changes.map(changeProblem).find(Boolean) ?? null;
+}
+
+const hash = (min, max) => (x) =>
+  typeof x === 'string' && new RegExp(`^[0-9a-f]{${min},${max}}$`).test(x);
+
+const RULES = {
+  schema: (v) =>
+    v === 3 ||
+    (v === 2 || v === 1
+      ? `schema ${v} card: GCF 0.4 keeps work items in gcf/work/<id>.md with schema: 3, ` +
+        'type and gate — there is no migration: put a card back into gcf/design/ as a unit ' +
+        'and run ai-factory gcf take'
+      : 'schema must be 3'),
+  id: (v) =>
+    isSlug(v) ||
+    (typeof v === 'number'
+      ? 'id must be a string: YAML read it as a number, put the slug in quotes'
+      : 'id must be a lowercase hyphen slug'),
+  type: (v) => ITEM_TYPES.includes(v) || `type must be ${ITEM_TYPES.join(' | ')}`,
+  gate: (v) => GATES.includes(v) || `gate must be ${GATES.join(' | ')}`,
+  title: (v) => isText(v) || 'title must be a non-empty string',
+  status: (v) =>
+    STORED.includes(v) ||
+    `status "${v}" is not storable (${STORED.join(', ')}; a terminal move deletes the file)`,
+  parent: (v) => nullable(isSlug)(v) || 'parent must be an item id or null',
+  children: (v) => slugList(v) || 'children must list item ids',
+  system: (v) => slugList(v) || 'system must list subsystem slugs',
+  depends: (v) => slugList(v) || 'depends must list ids',
+  pillars: (v) => slugList(v) || 'pillars must list pillar ids',
+  source: (v) => /^(GDD#[A-Za-z0-9_-]+|manual)$/.test(v) || 'source must be GDD#<id> or manual',
+  reopens: (v) => nullable(isSlug)(v) || 'reopens must name the id it reworks, or null',
+  milestone: (v) => nullable(isSlug)(v) || 'milestone must be a milestone name or null',
+  parallel: (v) => ['ok', 'serial'].includes(v) || 'parallel must be ok or serial',
+  plan: (v) => nullable(isText)(v) || 'plan must be a path or null',
+  tune_count: (v) => (Number.isInteger(v) && v >= 0) || 'tune_count must be an integer >= 0',
+  severity: (v) =>
+    nullable((x) => SEVERITIES.includes(x))(v) || `severity must be ${SEVERITIES.join(' | ')}`,
+  blocked: (v) => nullable(isText)(v) || 'blocked must be text or null',
+  since: (v) => nullable(hash(7, 64))(v) || 'since must be null or a commit hash',
+  frozen: (v) => hash(40, 40)(v) || 'frozen must be the sha1 of the body',
+  live: (v) => liveProblem(v) ?? true,
+  model: (v) => nullable(isText)(v) || 'model must be text or null',
+  effort: (v) => nullable(isText)(v) || 'effort must be text or null',
+  created: (v) => /^\d{4}-\d{2}-\d{2}$/.test(dateStr(v)) || 'created must be YYYY-MM-DD',
+};
+
+const dateStr = (v) => (v instanceof Date ? v.toISOString().slice(0, 10) : String(v));
+
+/** Per-field errors only — what item.schema.json also decides. */
+export function validateFields(data) {
+  if (data.schema !== undefined && data.schema !== 3) return [RULES.schema(data.schema)];
+  const errors = [];
+  for (const key of REQUIRED) if (!(key in data)) errors.push(`missing field: ${key}`);
+  for (const key of Object.keys(data)) {
+    if (!FIELDS.includes(key))
+      errors.push(
+        `unknown field: ${key}` +
+          (key === 'until' ? ' (until: is a line annotation, not frontmatter)' : '') +
+          (key === 'built_at' ? ' (schema 3 records since: when the item waits for you)' : ''),
+      );
+    else {
+      const res = RULES[key](data[key]);
+      if (res !== true) errors.push(res);
+    }
+  }
+
+  return errors;
+}
+
+const isUnit = (d) => UNIT_ITEM_TYPES.includes(d.type);
+
+// Which status, gate and type go together (Methodology §4): [broken when, message].
+/** @type {Array<[(d: any) => boolean, string]>} */
+const CROSS = [
+  [
+    (d) => d.status === 'awaiting-verdict' && d.gate !== 'verdict',
+    'awaiting-verdict needs gate: verdict',
+  ],
+  [
+    (d) => d.status === 'awaiting-decision' && d.gate !== 'decision' && d.type !== 'feature',
+    'awaiting-decision needs gate: decision (or a feature whose child died)',
+  ],
+  [(d) => d.type === 'feature' && d.gate !== 'auto', 'a feature always has gate: auto'],
+  [(d) => d.status === 'parked' && d.type !== 'bug', 'only a bug is parked'],
+  [
+    (d) => d.status === 'unplayed' && !['mechanic', 'resource'].includes(d.type),
+    'only a mechanic or a resource is unplayed',
+  ],
+  [
+    (d) => (d.status === 'unplayed') !== (d.frozen !== undefined),
+    'frozen: belongs to an unplayed item',
+  ],
+  [(d) => d.status === 'blocked' && !isText(d.blocked), 'a blocked item says why in blocked:'],
+  [(d) => d.status !== 'blocked' && isText(d.blocked), 'blocked: is set but status is not blocked'],
+  [(d) => d.type === 'bug' && !SEVERITIES.includes(d.severity), 'a bug needs severity'],
+  [(d) => d.type !== 'bug' && Boolean(d.severity), 'severity belongs to a bug'],
+  [(d) => d.children !== undefined && d.type !== 'feature', 'only a feature has children'],
+  [
+    (d) => isUnit(d) && !(Array.isArray(d.system) && d.system.length),
+    'a design-unit item lists >=1 subsystem in system:',
+  ],
+  [(d) => isUnit(d) && d.source === undefined, 'a design-unit item keeps its source:'],
+  [(d) => Boolean(d.parent) && d.parent === d.id, 'an item cannot be its own parent'],
+];
+
+/** Validate work item frontmatter. Returns a list of one-line errors (empty = valid). */
+export function validateItem(data) {
+  const fields = validateFields(data);
+  if (fields.length) return fields;
+
+  return CROSS.filter(([broken]) => broken(data)).map(([, message]) => message);
+}
+
+const UNTIL_OK = /^\[until:\s*(verdict\([a-z0-9-]+\)|retune\([a-z0-9-]+\)|manual\([^)]*\))\]$/;
+
+/** Validate every `[until: ...]` annotation in a body against the trigger grammar (§7.3). */
+export function validateUntil(body) {
+  const errors = [];
+  const lines = String(body).split('\n');
+  lines.forEach((line, i) => {
+    for (const m of line.matchAll(/\[until:[^\]]*\]/g)) {
+      if (!UNTIL_OK.test(m[0]))
+        errors.push(
+          `line ${i + 1}: bad until annotation ${m[0]} ` +
+            '(use verdict(<id>), retune(system) or manual(text))',
+        );
+    }
+  });
+
+  return errors;
+}