@starci/skills 1.1.0

package/scripts/validate-templates.mjs

@@ -0,0 +1,226 @@
+// Every operator document and every knowledge topic conforms to the template of its kind.
+//
+// A template is `templates/<kind>.template.md`: a human skeleton plus one fenced ```json block
+// tagged `template-contract`. The contract says which files it applies to, what the title must
+// match, which `##` sections must appear in which order (with `free` zones where a document may add
+// its own law sections), which table header a section or a rule must carry, what the closing
+// section is, and that a `.vi.md` mirror must exist and follow the Vietnamese form of the same
+// contract. The contract is the authority; the skeleton is how a human reads it.
+import { readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const CONTRACT_FENCE = /```json template-contract\r?\n([\s\S]*?)\r?\n```/;
+
+export async function loadTemplates(root) {
+  const dir = path.join(root, 'templates');
+  const templates = [];
+  for (const name of (await readdir(dir)).filter((f) => f.endsWith('.template.md')).sort()) {
+    const text = await readFile(path.join(dir, name), 'utf8');
+    const m = CONTRACT_FENCE.exec(text);
+    if (!m) throw new Error(`templates/${name}: no template-contract block`);
+    const contract = JSON.parse(m[1]);
+    if (contract.kind !== name.replace(/\.template\.md$/, '')) {
+      throw new Error(`templates/${name}: contract.kind must equal the file name`);
+    }
+    templates.push(contract);
+  }
+  return templates;
+}
+
+// Kind contracts describe markdown files that only exist inside a session: templates/kinds/<kind>.contract.json
+// is the authority (checked against contract.schema.json), <kind>.skeleton.md is the copyable skeleton and
+// must itself pass the contract. They claim nothing in the tree; validate-response loads them by kind.
+export async function loadKindTemplates(root) {
+  const dir = path.join(root, 'templates', 'kinds');
+  const { validateAgainst } = await import('./json-schema.mjs');
+  const schema = JSON.parse(await readFile(path.join(dir, 'contract.schema.json'), 'utf8'));
+  const kinds = new Map();
+  for (const name of (await readdir(dir)).filter((f) => f.endsWith('.contract.json')).sort()) {
+    const contract = JSON.parse(await readFile(path.join(dir, name), 'utf8'));
+    const rel = `templates/kinds/${name}`;
+    const errors = validateAgainst(schema, contract, rel);
+    if (errors.length) throw new Error(errors.join('\n'));
+    if (contract.kind !== name.replace(/\.contract\.json$/, '')) throw new Error(`${rel}: contract.kind must equal the file name`);
+    for (const s of contract.sections) {
+      if (!s.table && (s.rows || s.cell || s.minRows !== undefined || s.exactRows !== undefined)) throw new Error(`${rel}: section ${s.heading} has row rules but no table`);
+      if (s.table && s.cell) {
+        const cols = s.table.split('|').slice(1, -1).map((c) => c.trim());
+        for (const col of Object.keys(s.cell)) if (!cols.includes(col)) throw new Error(`${rel}: section ${s.heading} names cell column ${col}, which its table lacks`);
+      }
+    }
+    kinds.set(contract.kind, { ...contract, skeleton: `templates/kinds/${contract.kind}.skeleton.md` });
+  }
+  return kinds;
+}
+
+async function walk(dir) {
+  const out = [];
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+      out.push(...(await walk(full)));
+    } else out.push(full);
+  }
+  return out;
+}
+
+// Glob support is deliberately small: `*` within one segment, `**` across segments.
+function globToRegExp(glob) {
+  const escaped = glob
+    .split('/')
+    .map((seg) => (seg === '**' ? '(?:[^/]+/)*' : seg.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*')))
+    .join('/')
+    .replace(/\(\?:\[\^\/\]\+\/\)\*\//g, '(?:[^/]+/)*');
+  return new RegExp(`^${escaped}$`);
+}
+
+function headings(lines) {
+  const out = [];
+  lines.forEach((line, i) => {
+    if (/^## /.test(line)) out.push({ text: line.trimEnd(), line: i + 1 });
+  });
+  return out;
+}
+
+function tableHeadersBetween(lines, from, to) {
+  const out = [];
+  for (let i = from; i < to - 1; i += 1) {
+    if (lines[i].startsWith('|') && /^\|\s*-{3,}/.test(lines[i + 1])) out.push({ text: lines[i].trim().replace(/\s+/g, ' '), line: i + 1 });
+  }
+  return out;
+}
+
+// Data rows of the table whose header sits at `headerLine` (1-based): one array of trimmed cells per row.
+function tableRowsAt(lines, headerLine) {
+  const rows = [];
+  for (let i = headerLine + 1; i < lines.length && lines[i].startsWith('|'); i += 1) rows.push(lines[i].split('|').slice(1, -1).map((c) => c.trim()));
+  return rows;
+}
+const unquote = (s) => s.replace(/^`|`$/g, '');
+
+// A contract value is either one string (a single-language kind template) or { en, vi }.
+export function checkDocument(rel, text, contract, lang) {
+  const L = (v) => (typeof v === 'string' ? v : v?.[lang] ?? v?.en ?? v?.heading);
+  const errors = [];
+  const lines = text.split(/\r?\n/);
+  const title = lines[0] ?? '';
+  const titleRe = new RegExp(L(contract.title), 'u');
+  if (!titleRe.test(title)) errors.push(`${rel}:1: title must match ${L(contract.title)}`);
+
+  const all = headings(lines);
+  const ruleRe = contract.rules ? new RegExp(contract.rules.heading, 'u') : null;
+  const closingRe = contract.rules?.closing ? new RegExp(L(contract.rules.closing), 'u') : null;
+  const frame = all.filter((h) => !(ruleRe && ruleRe.test(h.text)) && !(closingRe && closingRe.test(h.text)));
+
+  // Walk the ordered section contract against the frame headings.
+  let cursor = 0;
+  let freeZone = false;
+  for (const section of contract.sections ?? []) {
+    if (section.free) { freeZone = true; continue; }
+    const re = new RegExp(L(section), 'u');
+    let found = -1;
+    for (let i = cursor; i < frame.length; i += 1) if (re.test(frame[i].text)) { found = i; break; }
+    if (found === -1) { errors.push(`${rel}: missing section ${L(section)}`); continue; }
+    if (found > cursor && !freeZone) {
+      for (let i = cursor; i < found; i += 1) errors.push(`${rel}:${frame[i].line}: unexpected section "${frame[i].text}" before ${L(section)}`);
+    }
+    if (section.table) {
+      const start = frame[found].line;
+      const next = all.find((h) => h.line > start);
+      const tables = tableHeadersBetween(lines, start, next ? next.line - 1 : lines.length);
+      const header = L(section.table);
+      if (tables.length === 0 || tables[0].text !== header) {
+        errors.push(`${rel}:${start}: section must open with the table ${header}`);
+      } else {
+        // Row-level shape: how many rows, which first-column values must appear, which cells must match.
+        const cols = header.split('|').slice(1, -1).map((c) => c.trim());
+        const rows = tableRowsAt(lines, tables[0].line);
+        const at = `${rel}:${tables[0].line}`;
+        if (section.minRows !== undefined && rows.length < section.minRows) errors.push(`${at}: table needs at least ${section.minRows} rows, found ${rows.length}`);
+        if (section.exactRows !== undefined && rows.length !== section.exactRows) errors.push(`${at}: table needs exactly ${section.exactRows} rows, found ${rows.length}`);
+        const firsts = new Set(rows.map((r) => unquote(r[0] ?? '')));
+        for (const need of section.rows ?? []) if (!firsts.has(need)) errors.push(`${at}: table lacks a row for ${need}`);
+        for (const [col, pattern] of Object.entries(section.cell ?? {})) {
+          const idx = cols.indexOf(col);
+          if (idx === -1) continue; // the column belongs to the other language's header
+          const cellRe = new RegExp(pattern, 'u');
+          rows.forEach((r, i) => { if (!cellRe.test(r[idx] ?? '')) errors.push(`${at}: row ${i + 1} cell ${col} "${r[idx] ?? ''}" does not match ${pattern}`); });
+        }
+      }
+    }
+    cursor = found + 1;
+    freeZone = false;
+  }
+  if (!freeZone && cursor < frame.length && contract.sections !== undefined) {
+    for (let i = cursor; i < frame.length; i += 1) errors.push(`${rel}:${frame[i].line}: unexpected trailing section "${frame[i].text}"`);
+  }
+
+  // Rules: each heading carries exactly one table of the published shape.
+  if (contract.rules) {
+    const rules = all.filter((h) => ruleRe.test(h.text));
+    if (contract.rules.required && rules.length === 0) errors.push(`${rel}: publishes no rule heading`);
+    rules.forEach((rule) => {
+      const next = all.find((h) => h.line > rule.line);
+      const tables = tableHeadersBetween(lines, rule.line, next ? next.line - 1 : lines.length);
+      if (tables.length !== 1) errors.push(`${rel}:${rule.line}: rule must carry exactly one table, found ${tables.length}`);
+      else if (tables[0].text !== L(contract.rules.table)) errors.push(`${rel}:${tables[0].line}: rule table must be ${L(contract.rules.table)}`);
+    });
+    if (closingRe) {
+      const last = all[all.length - 1];
+      if (!last || !closingRe.test(last.text)) errors.push(`${rel}: last section must be ${L(contract.rules.closing)}`);
+    }
+  }
+  return errors;
+}
+
+export async function validateTree(root) {
+  const templates = await loadTemplates(root);
+  const files = (await walk(root)).map((f) => path.relative(root, f).split(path.sep).join('/'));
+  const errors = [];
+  let checked = 0;
+  const claimed = new Map();
+  for (const contract of templates) {
+    const matchers = contract.applies.map(globToRegExp);
+    // INDEX files are reading indexes, not documents of a kind; they are outside every template.
+    const targets = files.filter((f) => f.endsWith('.md') && !f.endsWith('.vi.md') && !/(^|\/)INDEX\.md$/.test(f) && matchers.some((re) => re.test(f)));
+    for (const rel of targets) {
+      if (claimed.has(rel)) errors.push(`${rel}: claimed by templates ${claimed.get(rel)} and ${contract.kind}`);
+      claimed.set(rel, contract.kind);
+      const text = await readFile(path.join(root, rel), 'utf8');
+      errors.push(...checkDocument(rel, text, contract, 'en'));
+      checked += 1;
+      const viRel = rel.replace(/\.md$/, '.vi.md');
+      if (!files.includes(viRel)) { errors.push(`${rel}: no Vietnamese mirror ${viRel}`); continue; }
+      const viText = await readFile(path.join(root, viRel), 'utf8');
+      errors.push(...checkDocument(viRel, viText, contract, 'vi'));
+      checked += 1;
+    }
+  }
+  // A kind template may name one enforced example in the tree, so the shape a session file must take
+  // is visible to a reader before any session exists.
+  // Every kind's skeleton, and its example when it names one, must pass the kind's own contract.
+  let kinds = new Map();
+  try { kinds = await loadKindTemplates(root); } catch (e) { if (e.code !== 'ENOENT') throw e; }
+  for (const contract of kinds.values()) {
+    for (const rel of [contract.skeleton, contract.example].filter(Boolean)) {
+      if (!files.includes(rel)) { errors.push(`${rel}: named by kind ${contract.kind} but missing`); continue; }
+      errors.push(...checkDocument(rel, await readFile(path.join(root, rel), 'utf8'), contract, 'en'));
+      checked += 1;
+    }
+  }
+  return { errors, checked, templates: templates.length + kinds.size };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const { errors, checked, templates } = await validateTree(root);
+  if (errors.length > 0) {
+    process.stderr.write(`${errors.join('\n')}\n`);
+    process.exitCode = 1;
+  } else {
+    process.stdout.write(`templates enforced: ${templates} templates, ${checked} documents\n`);
+  }
+}

package/scripts/validate-templates.spec.mjs

@@ -0,0 +1,144 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { validateTree, checkDocument } from './validate-templates.mjs';
+
+// A synthetic tree: one template of each shape the validator understands, and documents that
+// satisfy or break it in exactly one way each.
+const contractOf = (kind, contract) => `# ${kind}\n\n\`\`\`json template-contract\n${JSON.stringify({ kind, ...contract }, null, 2)}\n\`\`\`\n`;
+
+const opContract = {
+  applies: ['ops/*/execute.md'],
+  title: { en: '^# Execute `[a-z.]+`$', vi: '^# Thực thi `[a-z.]+`$' },
+  sections: [
+    { en: '^## Single job$', vi: '^## Một việc duy nhất$' },
+    { free: true },
+    { en: '^## Sequence$', vi: '^## Trình tự$', table: { en: '| # | Step | Reads | Writes | Stops with |', vi: '| # | Bước | Đọc | Ghi | Dừng với |' } },
+    { en: '^## Mandatory attacks$', vi: '^## Các đòn tấn công bắt buộc$' },
+  ],
+  rules: null,
+};
+const ruleContract = {
+  applies: ['kb/**/*.md'],
+  title: { en: '^# .+ proof$', vi: '^# .+ proof$' },
+  sections: [],
+  rules: {
+    heading: '^## [A-Z]+-\\d+ — .+$',
+    table: { en: '| Case | When | Observe |', vi: '| Case | Dùng khi | Quan sát |' },
+    closing: { en: '^## What this file does not decide$', vi: '^## File này không quyết định$' },
+    required: true,
+  },
+};
+
+const goodExecute = (lang) => (lang === 'en'
+  ? '# Execute `x.y`\n\n## Single job\n\ntext\n\n## A law\n\ntext\n\n## Sequence\n\n| # | Step | Reads | Writes | Stops with |\n| --- | --- | --- | --- | --- |\n| 1 | a | b | c | d |\n\n## Mandatory attacks\n\n- one\n'
+  : '# Thực thi `x.y`\n\n## Một việc duy nhất\n\ntext\n\n## Một luật\n\ntext\n\n## Trình tự\n\n| # | Bước | Đọc | Ghi | Dừng với |\n| --- | --- | --- | --- | --- |\n| 1 | a | b | c | d |\n\n## Các đòn tấn công bắt buộc\n\n- one\n');
+const goodProof = (lang) => (lang === 'en'
+  ? '# Focus proof\n\nintro\n\n## FOCUS-1 — Visible focus\n\nline\n\n| Case | When | Observe |\n| --- | --- | --- |\n| Case 1 | a | b |\n\n## What this file does not decide\n\nlinks\n'
+  : '# Focus proof\n\nintro\n\n## FOCUS-1 — Focus nhìn thấy\n\nline\n\n| Case | Dùng khi | Quan sát |\n| --- | --- | --- |\n| Case 1 | a | b |\n\n## File này không quyết định\n\nlinks\n');
+
+function tree(mutate = () => {}) {
+  const root = mkdtempSync(join(tmpdir(), 'templates-'));
+  mkdirSync(join(root, 'templates'));
+  mkdirSync(join(root, 'ops', 'one'), { recursive: true });
+  mkdirSync(join(root, 'kb', 'proof'), { recursive: true });
+  writeFileSync(join(root, 'templates', 'execute.template.md'), contractOf('execute', opContract));
+  writeFileSync(join(root, 'templates', 'proof.template.md'), contractOf('proof', ruleContract));
+  const files = {
+    'ops/one/execute.md': goodExecute('en'),
+    'ops/one/execute.vi.md': goodExecute('vi'),
+    'kb/proof/focus.md': goodProof('en'),
+    'kb/proof/focus.vi.md': goodProof('vi'),
+    'kb/proof/INDEX.md': '# index\n\nnot a document of a kind\n',
+  };
+  mutate(files);
+  for (const [rel, text] of Object.entries(files)) {
+    if (text === null) continue;
+    writeFileSync(join(root, rel), text);
+  }
+  return root;
+}
+
+async function run(mutate) {
+  const root = tree(mutate);
+  try {
+    return await validateTree(root);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+test('conforming documents pass, INDEX files are not claimed, and both languages are counted', async () => {
+  const result = await run();
+  assert.deepEqual(result.errors, []);
+  assert.equal(result.checked, 4);
+  assert.equal(result.templates, 2);
+});
+
+test('a missing required section is named', async () => {
+  const result = await run((f) => { f['ops/one/execute.md'] = f['ops/one/execute.md'].replace('## Mandatory attacks\n\n- one\n', ''); });
+  assert.ok(result.errors.some((e) => e.includes('ops/one/execute.md') && e.includes('missing section ^## Mandatory attacks$')));
+});
+
+test('a section outside a free zone is rejected with its line', async () => {
+  const result = await run((f) => { f['ops/one/execute.md'] = f['ops/one/execute.md'].replace('# Execute `x.y`\n\n', '# Execute `x.y`\n\n## Preface\n\ntext\n\n'); });
+  assert.ok(result.errors.some((e) => /ops\/one\/execute\.md:3: unexpected section "## Preface"/.test(e)));
+});
+
+test('a section table with the wrong header is rejected', async () => {
+  const result = await run((f) => { f['ops/one/execute.md'] = f['ops/one/execute.md'].replace('| # | Step | Reads | Writes | Stops with |', '| Step | Notes |').replace('| --- | --- | --- | --- | --- |', '| --- | --- |'); });
+  assert.ok(result.errors.some((e) => e.includes('section must open with the table | # | Step | Reads | Writes | Stops with |')));
+});
+
+test('a rule with the wrong table, two tables, or no table is rejected', async () => {
+  const wrong = await run((f) => { f['kb/proof/focus.md'] = f['kb/proof/focus.md'].replace('| Case | When | Observe |', '| Case | When | Decide |'); });
+  assert.ok(wrong.errors.some((e) => e.includes('rule table must be | Case | When | Observe |')));
+  const two = await run((f) => { f['kb/proof/focus.md'] = f['kb/proof/focus.md'].replace('| Case 1 | a | b |\n', '| Case 1 | a | b |\n\n| Case | When | Observe |\n| --- | --- | --- |\n| Case 2 | c | d |\n'); });
+  assert.ok(two.errors.some((e) => e.includes('exactly one table, found 2')));
+  const none = await run((f) => { f['kb/proof/focus.md'] = f['kb/proof/focus.md'].replace('| Case | When | Observe |\n| --- | --- | --- |\n| Case 1 | a | b |\n', ''); });
+  assert.ok(none.errors.some((e) => e.includes('exactly one table, found 0')));
+});
+
+test('the closing section must come last and a rule file must publish a rule', async () => {
+  const notLast = await run((f) => { f['kb/proof/focus.md'] = `${f['kb/proof/focus.md']}\n## Afterword\n\ntext\n`; });
+  assert.ok(notLast.errors.some((e) => e.includes('last section must be ^## What this file does not decide$')));
+  const noRule = await run((f) => { f['kb/proof/focus.md'] = '# Focus proof\n\nintro\n\n## What this file does not decide\n\nlinks\n'; });
+  assert.ok(noRule.errors.some((e) => e.includes('publishes no rule heading')));
+});
+
+test('a title outside the pattern is rejected in either language', async () => {
+  const result = await run((f) => { f['ops/one/execute.vi.md'] = f['ops/one/execute.vi.md'].replace('# Thực thi `x.y`', '# Execute `x.y`'); });
+  assert.ok(result.errors.some((e) => e.includes('ops/one/execute.vi.md:1: title must match')));
+});
+
+test('a missing Vietnamese mirror is rejected and the English document is still checked', async () => {
+  const result = await run((f) => { f['kb/proof/focus.vi.md'] = null; });
+  assert.ok(result.errors.some((e) => e.includes('no Vietnamese mirror kb/proof/focus.vi.md')));
+  assert.equal(result.checked, 3);
+});
+
+test('row-level shape: minRows, exactRows, rows and cell are enforced, and a kind contract may be single-language', () => {
+  const contract = {
+    kind: 'critique', applies: [],
+    title: '^# critique$',
+    sections: [{ en: '^## Attacks$', table: '| Path | Verdict |', exactRows: 2, rows: ['a', 'b'], cell: { Verdict: '^(holds|fails)$' } }],
+    rules: null,
+  };
+  const good = '# critique\n\n## Attacks\n\n| Path | Verdict |\n| --- | --- |\n| `a` | holds |\n| b | fails |\n';
+  assert.deepEqual(checkDocument('c.md', good, contract, 'en'), []);
+  const tooFew = checkDocument('c.md', good.replace('| b | fails |\n', ''), contract, 'en');
+  assert.ok(tooFew.some((e) => e.includes('exactly 2 rows, found 1')) && tooFew.some((e) => e.includes('lacks a row for b')));
+  const badCell = checkDocument('c.md', good.replace('| b | fails |', '| b | maybe |'), contract, 'en');
+  assert.ok(badCell.some((e) => e.includes('cell Verdict "maybe" does not match')));
+  const min = checkDocument('c.md', good, { ...contract, sections: [{ en: '^## Attacks$', table: '| Path | Verdict |', minRows: 3 }] }, 'en');
+  assert.ok(min.some((e) => e.includes('at least 3 rows, found 2')));
+});
+
+test('a template whose kind does not match its file name is refused', async () => {
+  const root = tree();
+  writeFileSync(join(root, 'templates', 'other.template.md'), contractOf('mismatch', ruleContract));
+  await assert.rejects(() => validateTree(root), /contract\.kind must equal the file name/);
+  rmSync(root, { recursive: true, force: true });
+});

package/scripts/validate-workflows.mjs

@@ -0,0 +1,106 @@
+// A workflow is a pre-composed chain of operators: an ordered list of steps, each step a list of
+// branches that run in parallel. workflows/*.json are examples the entry may reuse when a request
+// matches their `when`; otherwise the entry composes its own chain under the same rules this script
+// enforces: every operator exists; every requirement preset names a declared field; every required
+// Input of a branch is produced by an earlier step; branches of one step share no write alias; a loop
+// goes back to an earlier step and carries a round cap; the chain ends where it says it ends.
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { loadOperatorPackages, cellAliases, kindOf, isYes } from './operator-md.mjs';
+import { loadAliasRegistry, baseOf } from './alias-registry.mjs';
+
+const unquote = (s) => String(s ?? '').trim().replace(/^`|`$/g, '');
+
+export async function validateWorkflows(root) {
+  const errors = [];
+  const packages = (await loadOperatorPackages(root)).filter((p) => p.shape === 'v9');
+  const aliases = (await loadAliasRegistry(root)).aliases;
+  const ops = new Map(packages.map((p) => {
+    const op = p.en;
+    const writes = new Set();
+    for (const s of op.tables.steps?.rows ?? []) for (const a of cellAliases(s.writes)) writes.add(baseOf(aliases, a) ?? a);
+    // The checkout roles the operator's required Context binds (@workspaces/fe, @workspaces/be, ...).
+    const roles = new Set();
+    for (const r of op.tables.context?.rows ?? []) { const a = cellAliases(r.alias)[0]; const m = a && /^@workspaces\/(fe|be)\b/.exec(a); if (m && isYes(r.required)) roles.add(m[1]); }
+    return [p.manifest.id, {
+      fields: new Set((op.tables.requirements?.rows ?? []).map((r) => unquote(r.field))),
+      required: (op.tables.inputs?.rows ?? []).filter((r) => isYes(r.required)).map((r) => kindOf(r.kind)),
+      outputs: new Set((op.tables.outputs?.rows ?? []).map((r) => kindOf(r.kind))),
+      next: new Set((op.tables.next?.rows ?? []).map((r) => unquote(r.operator))),
+      roles,
+      writes,
+    }];
+  }));
+  const dir = path.join(root, 'workflows');
+  const files = (await readdir(dir)).filter((f) => f.endsWith('.json')).sort();
+  const ids = new Set();
+  for (const file of files) {
+    const rel = `workflows/${file}`;
+    let wf; try { wf = JSON.parse(await readFile(path.join(dir, file), 'utf8')); } catch (e) { errors.push(`${rel}: ${e.message}`); continue; }
+    if (wf.schemaVersion !== 9) errors.push(`${rel}: schemaVersion must be 9`);
+    if (wf.id !== file.replace(/\.json$/, '')) errors.push(`${rel}: id must equal the file name`);
+    if (ids.has(wf.id)) errors.push(`${rel}: duplicate id`); ids.add(wf.id);
+    if (!wf.when?.en || !wf.when?.vi) errors.push(`${rel}: when.en and when.vi are required`);
+    if (!Array.isArray(wf.chain) || wf.chain.length === 0) { errors.push(`${rel}: chain must be a non-empty array of steps`); continue; }
+    const produced = new Set();
+    const positions = new Map(); // operator -> first step index
+    const boundRoles = new Set(); // workspace.bind roles bound by earlier steps
+    let previousOps = null;
+    wf.chain.forEach((step, n) => {
+      // Adjacency: every operator of this step must be a Next of some operator of the previous step,
+      // or the same operator re-entered (a resume or a second mode of the same job).
+      if (Array.isArray(step) && previousOps) {
+        for (const b of step) {
+          const allowed = previousOps.some((prev) => prev === b.operator || (ops.get(prev)?.next ?? new Set()).has(b.operator));
+          if (!allowed) errors.push(`${rel}: step ${n + 1} runs ${b.operator}, which no Next table of step ${n} (${previousOps.join(', ')}) permits`);
+        }
+      }
+      if (!Array.isArray(step) || step.length === 0) { errors.push(`${rel}: step ${n + 1} must be a non-empty array of branches`); return; }
+      if (step.length > 3) errors.push(`${rel}: step ${n + 1} has ${step.length} branches; at most 3 run in parallel`);
+      const stepProduces = new Set();
+      const seenWrites = new Map();
+      step.forEach((b, m) => {
+        const at = `${rel}: step ${n + 1} branch ${m + 1}`;
+        const op = ops.get(b.operator);
+        if (!op) { errors.push(`${at}: unknown operator ${b.operator}`); return; }
+        if (!positions.has(b.operator)) positions.set(b.operator, n);
+        for (const key of Object.keys(b.requirements ?? {})) if (!op.fields.has(key)) errors.push(`${at}: requirement ${key} is not a field of ${b.operator}`);
+        for (const kind of op.required) if (!produced.has(kind)) errors.push(`${at}: ${b.operator} requires input ${kind}, which no earlier step produces`);
+        // A required @workspaces/<role> context needs a workspace.bind of that role in an earlier step.
+        if (b.operator !== 'workspace.bind') for (const role of op.roles) if (!boundRoles.has(role)) errors.push(`${at}: ${b.operator} requires @workspaces/${role}, which no earlier workspace.bind (role ${role}) bound`);
+        if (b.fanout !== undefined && b.fanout !== 'matrix') errors.push(`${at}: fanout must be "matrix"`);
+        if (b.maxParallel !== undefined && !(Number.isInteger(b.maxParallel) && b.maxParallel >= 1 && b.maxParallel <= 3)) errors.push(`${at}: maxParallel must be 1..3`);
+        for (const w of op.writes) {
+          if (seenWrites.has(w)) errors.push(`${at}: ${b.operator} and ${seenWrites.get(w)} both write ${w} in the same step; branches of one step must not share a write alias`);
+          seenWrites.set(w, b.operator);
+        }
+        for (const k of op.outputs) stepProduces.add(k);
+      });
+      for (const k of stepProduces) produced.add(k);
+      for (const b of step) if (b.operator === 'workspace.bind' && b.requirements?.role) boundRoles.add(b.requirements.role);
+      previousOps = step.map((b) => b.operator);
+    });
+    for (const loop of wf.loops ?? []) {
+      const from = positions.get(loop.from); const to = positions.get(loop.to);
+      if (from === undefined || to === undefined) errors.push(`${rel}: loop names an operator outside the chain (${loop.from} → ${loop.to})`);
+      else if (to >= from) errors.push(`${rel}: loop ${loop.from} → ${loop.to} must go back to an earlier step`);
+      if (!(Number.isInteger(loop.maxRounds) && loop.maxRounds >= 1)) errors.push(`${rel}: loop ${loop.from} → ${loop.to} needs maxRounds ≥ 1`);
+      if (!loop.when) errors.push(`${rel}: loop ${loop.from} → ${loop.to} needs a when`);
+    }
+    const last = wf.chain[wf.chain.length - 1];
+    const lastOps = Array.isArray(last) ? last.map((b) => b.operator) : [];
+    if (wf.ends !== 'user' && !lastOps.includes(wf.ends)) errors.push(`${rel}: ends must be "user" or an operator of the last step (${lastOps.join(', ')})`);
+  }
+  // The README lists every example.
+  const readme = await readFile(path.join(dir, 'README.md'), 'utf8');
+  for (const id of ids) if (!readme.includes(`\`${id}\``)) errors.push(`workflows/README.md: does not list ${id}`);
+  return { errors, count: files.length };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const { errors, count } = await validateWorkflows(root);
+  if (errors.length) { process.stderr.write(`${errors.join('\n')}\n`); process.exitCode = 1; } else process.stdout.write(`workflows closed: ${count} examples\n`);
+}