gcf-aif-ext 0.2.7 → 0.4.0

package/lib/transitions.js

@@ -1,28 +1,43 @@
-// GCF-PRD §7.1. `none` = materialization (no card file yet).
-// `validated` and `killed` are terminal and NEVER stored: the verdict that produces them
-// also deletes the card file, so a card file carrying one is a П1 violation (pre-commit check).
-const STORED = new Set(['proposed', 'built', 'tuning']);
-export const TERMINAL = new Set(['validated', 'killed']);
+// Methodology §4. A work item FILE carries one of the stored statuses; `running` and `verify` are
+// read from the run (worktree + session), never written. A terminal move deletes the file and
+// writes a history or graveyard line in the same commit, so no terminal status is ever stored.
+export const STORED = [
+  'ready',
+  'awaiting-verdict',
+  'awaiting-decision',
+  'blocked',
+  'parked',
+  'unplayed',
+];
 
-const LEGAL = new Set([
-  'none>proposed',
-  'proposed>built', // agent flips frontmatter itself on implementation commit (GCF-PRD §5.1)
-  'built>tuning', //   /gcf-verdict tune
-  'tuning>built', //   agent re-built after tuning
-  'built>validated', // /gcf-verdict keep — file is deleted in the same atomic commit
-  'built>killed', //   /gcf-verdict kill — file is deleted in the same atomic commit
-]);
+// The status each command takes an item from (§4.1). `drop` leaves from any stored status.
+const FROM = {
+  submit: ['ready'],
+  close: ['ready'],
+  'verdict:keep': ['awaiting-verdict', 'unplayed'],
+  'verdict:tune': ['awaiting-verdict', 'unplayed'],
+  'verdict:kill': ['awaiting-verdict', 'unplayed'],
+  'decide:go': ['awaiting-decision'],
+  'decide:no': ['awaiting-decision', 'ready'],
+  'decide:wontfix': ['ready', 'blocked', 'parked'],
+  'decide:known': ['ready', 'blocked'],
+  'decide:close': ['awaiting-decision'],
+  'decide:continue': ['awaiting-decision'],
+  'decide:kill': ['awaiting-decision', 'ready'],
+  block: ['ready'],
+  unblock: ['blocked', 'parked'],
+  drop: STORED,
+};
 
-export function isLegal(from, to) {
-  return LEGAL.has(`${from}>${to}`);
+/** True when `move` (`close`, `verdict:keep`, …) may start from `status`. */
+export function allowedFrom(move, status) {
+  return (FROM[move] ?? []).includes(status);
 }
 
-/** Statuses reachable from `from`, for error messages. */
-export function legalTargets(from) {
-  return [...LEGAL].filter((t) => t.startsWith(`${from}>`)).map((t) => t.split('>')[1]);
-}
+/** Statuses `move` starts from, for error messages. */
+export const fromOf = (move) => FROM[move] ?? [];
 
-/** A status a card FILE may carry. Terminal statuses exist only in the transition itself. */
+/** A status an item FILE may carry. */
 export function isStorable(status) {
-  return STORED.has(status);
+  return STORED.includes(status);
 }

package/lib/unit-ops.js

@@ -0,0 +1,297 @@
+// 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, SLUG_RE, listOf } from './design.js';
+import { buildLedger } from './ledger.js';
+import { designCheck } from './design-check.js';
+import { atomicWrite, withFileRollback } from './safe-path.js';
+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) {
+  // 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));
+  if (end < 0) end = lines.length;
+
+  return `${[...lines.slice(0, at), ...lines.slice(end)]
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trimEnd()}\n`.replace(/\n/g, eol);
+}
+
+/** backlog.md without the line of `id`. */
+export const backlogWithout = (text, id) =>
+  String(text)
+    .split('\n')
+    .filter((l) => l.match(/^- (\S+)/)?.[1] !== id)
+    .join('\n');
+
+/** The single design unit `id`, or an error naming where the id lives instead. */
+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})`);
+  }
+
+  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') };
+}
+
+async function cutUnit(paths, id) {
+  await atomicWrite(paths.design, removeUnit(await readFile(paths.design, 'utf8'), id));
+  if (existsSync(paths.backlog))
+    await atomicWrite(paths.backlog, backlogWithout(await readFile(paths.backlog, 'utf8'), id));
+}
+
+/** 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: 3,
+    id: unit.id,
+    type: h.type,
+    gate,
+    ...(h.title ? { title: h.title } : {}),
+    status: 'ready',
+    ...(parent ? { parent } : {}),
+    system: listOf(h.system),
+    depends: listOf(h.depends),
+    pillars: pillars === 'TBD' ? [] : pillars,
+    source: h.source,
+    ...(h.reopens ? { reopens: h.reopens } : {}),
+    ...(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 or a blocking design-check finding`;
+    throw new Error(`${unit.id} is not ready (${why}): answer it in design/ first`);
+  }
+}
+
+/**
+ * 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 takeUnits(
+  projectDir,
+  ids,
+  { feature = null, today = new Date().toISOString().slice(0, 10) } = {},
+) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  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 = 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 { 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. */
+export function gitText(projectDir, spec) {
+  const res = spawnSync('git', ['show', spec], { cwd: projectDir, encoding: 'utf8' });
+
+  return res.status === 0 ? res.stdout : '';
+}
+
+/**
+ * True when `file` differs from HEAD in the index or on disk. Line endings do not count: a file
+ * stored with CRLF and checked out with LF is not an edit.
+ */
+function uncommitted(projectDir, file) {
+  const rel = `./${path.relative(projectDir, file).replaceAll('\\', '/')}`;
+  const norm = (t) => String(t).replace(/\r\n/g, '\n').trimEnd();
+  const head = norm(gitText(projectDir, `HEAD:${rel}`));
+  const disk = norm(existsSync(file) ? readFileSync(file, 'utf8') : '');
+
+  return head !== norm(gitText(projectDir, `:${rel}`)) || head !== disk;
+}
+
+/**
+ * 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. `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
+ */
+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) => !inputs.includes(f) && uncommitted(projectDir, f))
+    : [];
+  if (dirty.length) {
+    const names = dirty.map((f) => path.relative(projectDir, f)).join(', ');
+    throw new Error(
+      `commit or stash these first (an answered unit is committed before its move), ` +
+        `${message} would carry them: ${names}`,
+    );
+  }
+
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const touched = [...files, path.join(root, 'INDEX.md')];
+  /** @type {string | null} */
+  let hash = null;
+  await withFileRollback(
+    touched,
+    async () => {
+      await mutate();
+      await writeIndex(root);
+      if (commit) hash = commitPaths(projectDir, message, touched);
+    },
+    { gitCwd: commit ? path.resolve(projectDir) : null },
+  );
+
+  return hash;
+}
+
+/**
+ * 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 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`);
+  const paths = basePaths(root, unit);
+  const doc = constraints.length ? await openSystemDoc(root, unit.system) : null;
+  const files = [paths.design, paths.backlog, path.join(root, 'history.md')];
+  if (doc) files.push(doc.file);
+  const mutate = async () => {
+    await cutUnit(paths, id);
+    await recordLine(root, id, 'done');
+    if (doc) await addConstraints(doc, id, constraints);
+  };
+
+  return {
+    id,
+    hash: await commitMove(projectDir, `gcf(done): ${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 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 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 () => {
+    const lineTags = tags.length ? tags : system === 'TBD' ? [] : system;
+    await buryLine(root, id, { type, reason, tags: lineTags });
+    await cutUnit(paths, id);
+  };
+
+  return {
+    id,
+    hash: await commitMove(projectDir, `gcf(drop): ${id}`, { files, mutate, commit }),
+  };
+}

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;
+}