@starci/skills 1.1.0

package/scripts/install-cli.spec.mjs

@@ -0,0 +1,74 @@
+// The installer must produce a tree the validators accept, refuse to overwrite a .claude it did not
+// install, keep a person's local edit across update, and write the two bootstraps exactly once.
+import assert from 'node:assert/strict';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { test as nodeTest } from 'node:test';
+import { fileURLToPath } from 'node:url';
+// An installed tree has no bin/ and no package.json beside scripts/, so doctor skips this file there.
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const isPackage = existsSync(path.join(root, 'bin', 'starci-skills.mjs')) && existsSync(path.join(root, 'package.json'));
+const { PAYLOAD, init, update, doctor } = isPackage ? await import('../bin/starci-skills.mjs') : {};
+const pkg = isPackage ? JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8')) : null;
+const test = (name, fn) => nodeTest(name, { skip: isPackage ? false : 'not the package checkout' }, fn);
+const quiet = () => {};
+
+function freshRepo() {
+  const repo = mkdtempSync(path.join(tmpdir(), 'starci-skills-'));
+  writeFileSync(path.join(repo, '.gitignore'), 'node_modules/\n');
+  return repo;
+}
+
+test('package.json ships exactly the runtime paths the installer copies, plus bin and the READMEs', () => {
+  const shipped = pkg.files.map((f) => f.replace(/\/$/, ''));
+  for (const p of PAYLOAD) assert.ok(shipped.includes(p), `${p} is copied by init but not in package.json files`);
+  for (const stale of ['sites', 'docs', 'tests', 'onichan.md', '.github']) assert.ok(!shipped.includes(stale), `${stale} must not ship`);
+  assert.equal(pkg.bin['starci-skills'], 'bin/starci-skills.mjs');
+  assert.equal(pkg.publishConfig.access, 'public');
+  assert.match(readFileSync(path.join(root, 'INDEX.md'), 'utf8'), new RegExp(`^# StarCi Skills ${pkg.version.replace(/\./g, '\\.')}$`, 'm'));
+});
+
+test('init installs the tree, writes both bootstraps and the sessions ignore, and doctor --quick passes', () => {
+  const repo = freshRepo();
+  try {
+    const manifest = init({ dir: repo, force: false, bootstrap: true }, quiet);
+    assert.equal(manifest.version, pkg.version);
+    for (const p of PAYLOAD) assert.ok(existsSync(path.join(repo, '.claude', p)), `${p} not installed`);
+    assert.ok(!existsSync(path.join(repo, '.claude', 'package.json')), 'the package manifest is not part of the runtime');
+    for (const name of ['CLAUDE.md', 'AGENTS.md']) assert.match(readFileSync(path.join(repo, name), 'utf8'), /\.claude\/INDEX\.md/);
+    assert.match(readFileSync(path.join(repo, '.gitignore'), 'utf8'), /^\.worktrees\/sessions\/$/m);
+    assert.equal(doctor({ dir: repo, quick: true }, quiet), 0);
+  } finally { rmSync(repo, { recursive: true, force: true }); }
+});
+
+test('init refuses a populated .claude it did not install, and --force replaces only runtime paths', () => {
+  const repo = freshRepo();
+  try {
+    mkdirSync(path.join(repo, '.claude'));
+    writeFileSync(path.join(repo, '.claude', 'settings.json'), '{}\n');
+    assert.throws(() => init({ dir: repo, force: false, bootstrap: false }, quiet), /was not installed by/);
+    init({ dir: repo, force: true, bootstrap: false }, quiet);
+    assert.ok(existsSync(path.join(repo, '.claude', 'settings.json')), 'a file outside the runtime paths survives --force');
+    assert.ok(!existsSync(path.join(repo, 'CLAUDE.md')), '--no-bootstrap writes no bootstrap');
+  } finally { rmSync(repo, { recursive: true, force: true }); }
+});
+
+test('update keeps a locally changed file and lists it; --force takes the package version', () => {
+  const repo = freshRepo();
+  try {
+    init({ dir: repo, force: false, bootstrap: false }, quiet);
+    const target = path.join(repo, '.claude', 'workflows', 'README.md');
+    const original = readFileSync(target, 'utf8');
+    writeFileSync(target, `${original}\nlocal note\n`);
+    unlinkSync(path.join(repo, '.claude', 'routing.json'));
+    const lines = [];
+    const manifest = update({ dir: repo, force: false }, (l) => lines.push(l));
+    assert.deepEqual(manifest.keptLocal, ['workflows/README.md']);
+    assert.match(readFileSync(target, 'utf8'), /local note/);
+    assert.ok(existsSync(path.join(repo, '.claude', 'routing.json')), 'a deleted runtime file comes back');
+    assert.ok(lines.some((l) => l.startsWith('kept workflows/README.md')));
+    update({ dir: repo, force: true }, quiet);
+    assert.equal(readFileSync(target, 'utf8'), original);
+  } finally { rmSync(repo, { recursive: true, force: true }); }
+});

package/scripts/json-schema.mjs

@@ -0,0 +1,94 @@
+// The one JSON Schema checker the tree uses: the same subset every operator's validation.mjs carried
+// (types, enum, const, $ref local, allOf/oneOf/anyOf, if/then/else, string, number, array and object
+// keywords), lifted to scripts/ so validate-step, the kind schemas under templates/kinds, and the step
+// gates under templates/step share one implementation.
+import { readFileSync } from 'node:fs';
+
+function isObject(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+function jsonType(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  if (Number.isInteger(value)) return 'integer';
+  return typeof value;
+}
+function resolveLocalRef(schema, ref) {
+  if (!ref.startsWith('#/')) throw new Error(`unsupported non-local schema reference ${ref}`);
+  return ref.slice(2).split('/').reduce((current, key) => current?.[key.replaceAll('~1', '/').replaceAll('~0', '~')], schema);
+}
+function inspect(schema, rule, value, at, errors) {
+  if (rule.$ref) return inspect(schema, resolveLocalRef(schema, rule.$ref), value, at, errors);
+  for (const item of rule.allOf ?? []) inspect(schema, item, value, at, errors);
+  if (rule.oneOf || rule.anyOf) {
+    const branches = rule.oneOf ?? rule.anyOf;
+    const matches = branches.filter((branch) => { const e = []; inspect(schema, branch, value, at, e); return e.length === 0; }).length;
+    if ((rule.oneOf && matches !== 1) || (rule.anyOf && matches === 0)) errors.push(`${at}: no unique allowed schema branch`);
+    return;
+  }
+  if (rule.if) {
+    const c = []; inspect(schema, rule.if, value, at, c);
+    if (c.length === 0 && rule.then) inspect(schema, rule.then, value, at, errors);
+    if (c.length > 0 && rule.else) inspect(schema, rule.else, value, at, errors);
+  }
+  if (Object.hasOwn(rule, 'const') && value !== rule.const) errors.push(`${at}: expected ${JSON.stringify(rule.const)}`);
+  if (rule.enum && !rule.enum.includes(value)) errors.push(`${at}: value is outside the allowed enum`);
+  if (rule.type) {
+    const types = Array.isArray(rule.type) ? rule.type : [rule.type];
+    const actual = jsonType(value);
+    if (!types.some((type) => type === actual || (type === 'number' && typeof value === 'number'))) { errors.push(`${at}: expected ${types.join('|')}, got ${actual}`); return; }
+  }
+  if (typeof value === 'string') {
+    if (rule.minLength !== undefined && value.length < rule.minLength) errors.push(`${at}: string is too short`);
+    if (rule.maxLength !== undefined && value.length > rule.maxLength) errors.push(`${at}: string is too long`);
+    if (rule.pattern && !new RegExp(rule.pattern).test(value)) errors.push(`${at}: string does not match ${rule.pattern}`);
+    if (rule.format === 'date-time' && Number.isNaN(Date.parse(value))) errors.push(`${at}: invalid date-time`);
+  }
+  if (typeof value === 'number') {
+    if (rule.minimum !== undefined && value < rule.minimum) errors.push(`${at}: value is below minimum`);
+    if (rule.maximum !== undefined && value > rule.maximum) errors.push(`${at}: value exceeds maximum`);
+  }
+  if (Array.isArray(value)) {
+    if (rule.minItems !== undefined && value.length < rule.minItems) errors.push(`${at}: array is too short`);
+    if (rule.maxItems !== undefined && value.length > rule.maxItems) errors.push(`${at}: array is too long`);
+    if (rule.uniqueItems && new Set(value.map((item) => JSON.stringify(item))).size !== value.length) errors.push(`${at}: duplicate items are forbidden`);
+    if (rule.items) value.forEach((item, index) => inspect(schema, rule.items, item, `${at}[${index}]`, errors));
+  }
+  if (isObject(value)) {
+    for (const key of rule.required ?? []) if (!Object.hasOwn(value, key)) errors.push(`${at}.${key}: required`);
+    const properties = rule.properties ?? {};
+    if (rule.additionalProperties === false) for (const key of Object.keys(value)) if (!Object.hasOwn(properties, key)) errors.push(`${at}.${key}: unexpected property`);
+    else if (isObject(rule.additionalProperties)) for (const [key, child] of Object.entries(value)) if (!Object.hasOwn(properties, key)) inspect(schema, rule.additionalProperties, child, `${at}.${key}`, errors);
+    for (const [key, child] of Object.entries(properties)) if (Object.hasOwn(value, key)) inspect(schema, child, value[key], `${at}.${key}`, errors);
+  }
+}
+// Path traversal and unbounded strings are refused everywhere, whatever the schema says.
+function hygiene(value) {
+  const errors = [];
+  const visit = (current, at) => {
+    if (typeof current === 'string') {
+      if (current.length > 8192) errors.push(`${at}: string exceeds the contract limit`);
+      if (!at.endsWith('.$schema') && /(^|[\\/])\.\.([\\/]|$)/.test(current) && !/^\.\.\/step-\d+-\d+\//.test(current)) errors.push(`${at}: path traversal is forbidden`);
+      return;
+    }
+    if (Array.isArray(current)) { if (current.length > 512) errors.push(`${at}: array exceeds the contract limit`); current.forEach((item, i) => visit(item, `${at}[${i}]`)); return; }
+    if (isObject(current)) for (const [key, child] of Object.entries(current)) visit(child, `${at}.${key}`);
+  };
+  visit(value, '$');
+  return errors;
+}
+export function validateAgainst(schema, value, at = '$') {
+  const errors = [];
+  inspect(schema, schema, value, at, errors);
+  if (errors.length === 0) errors.push(...hygiene(value));
+  return errors;
+}
+
+// The shape the old per-operator validation.mjs exported; scripts/workspace-portable.mjs (called by the
+// backend package.json) still builds its route validators this way.
+export function validatorFor(schemaUrl, semantic = () => []) {
+  const schema = JSON.parse(readFileSync(schemaUrl, 'utf8'));
+  return (value) => {
+    const errors = validateAgainst(schema, value);
+    if (errors.length === 0) errors.push(...semantic(value));
+    return { valid: errors.length === 0, errors };
+  };
+}

package/scripts/operator-md.mjs

@@ -0,0 +1,96 @@
+// operator.md is the one authored file of an operator. This module is the one place it is parsed, so
+// validate-operator, validate-alias, validate-routing, generate-operators-index and validate-step
+// cannot disagree about which table says what. Tables are read by position, so the English file and
+// its Vietnamese mirror parse identically; the headings differ per language and are listed here.
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+export const HEADINGS = {
+  en: { job: '## Job', context: '## Context', inputs: '## Inputs', requirements: '## Requirements', steps: '## Steps', outputs: '## Outputs', stops: '## Stops', next: '## Next' },
+  vi: { job: '## Việc', context: '## Context', inputs: '## Đầu vào', requirements: '## Yêu cầu', steps: '## Các bước', outputs: '## Đầu ra', stops: '## Dừng', next: '## Kế tiếp' },
+};
+export const COLUMNS = {
+  context: ['alias', 'bind', 'required'],
+  inputs: ['kind', 'from', 'required'],
+  requirements: ['field', 'type', 'default', 'ask'],
+  steps: ['n', 'step', 'params', 'reads', 'writes', 'stops'],
+  outputs: ['kind', 'file', 'type', 'required'],
+  stops: ['code', 'disposition'],
+  next: ['when', 'operator'],
+};
+export const YES = new Set(['yes', 'có']);
+export const ALIAS = /@[a-z][a-z-]*(?:\/[A-Za-z0-9_<>.@#:-]+)*/g;
+const strip = (s) => s.replace(/^`|`$/g, '');
+
+function firstTable(lines, from, to) {
+  for (let i = from; i < to - 1; i += 1) {
+    if (lines[i].startsWith('|') && /^\|\s*-{3,}/.test(lines[i + 1])) {
+      const rows = [];
+      for (let j = i + 2; j < to && lines[j].startsWith('|'); j += 1) rows.push(lines[j].split('|').slice(1, -1).map((c) => c.trim()));
+      return { header: lines[i].split('|').slice(1, -1).map((c) => c.trim()), rows, line: i + 1 };
+    }
+  }
+  return null;
+}
+
+export function parseOperatorMd(text, lang = 'en') {
+  const lines = text.split(/\r?\n/);
+  const h = HEADINGS[lang];
+  const heads = lines.map((l, i) => ({ l: l.trimEnd(), i })).filter((x) => x.l.startsWith('## '));
+  const sectionOf = (heading) => {
+    const idx = heads.findIndex((x) => x.l === heading);
+    if (idx === -1) return null;
+    const from = heads[idx].i + 1;
+    const to = idx + 1 < heads.length ? heads[idx + 1].i : lines.length;
+    return { from, to, line: heads[idx].i + 1 };
+  };
+  const out = { id: (lines[0] ?? '').replace(/^#\s*/, '').replace(/`/g, '').trim(), lang, tables: {}, job: '' };
+  const job = sectionOf(h.job);
+  if (job) out.job = lines.slice(job.from, job.to).map((l) => l.trim()).filter(Boolean).join(' ');
+  for (const key of Object.keys(COLUMNS)) {
+    const sec = sectionOf(h[key]);
+    if (!sec) { out.tables[key] = null; continue; }
+    const table = firstTable(lines, sec.from, sec.to);
+    if (!table) { out.tables[key] = null; continue; }
+    const cols = COLUMNS[key];
+    out.tables[key] = {
+      line: table.line,
+      header: table.header,
+      rows: table.rows.map((cells, r) => {
+        const row = { _line: table.line + 2 + r };
+        cols.forEach((c, i) => { row[c] = cells[i] ?? ''; });
+        return row;
+      }),
+    };
+  }
+  return out;
+}
+
+// Convenience views over the parsed tables.
+export const cellCodes = (cell) => [...cell.matchAll(/`([A-Z][A-Z0-9_]+)`/g)].map((m) => m[1]);
+export const cellParams = (cell) => (cell.trim() === '—' || cell.trim() === '' ? [] : [...cell.matchAll(/`([a-zA-Z][A-Za-z0-9_]*)`/g)].map((m) => m[1]));
+export const cellAliases = (cell) => [...cell.matchAll(ALIAS)].map((m) => m[0]);
+// Files are branch-relative: response/<x>.md, response/data/…, response/artifacts/…, response/response.json,
+// or <exchange>/response/… for a nested exchange.
+export const cellFiles = (cell) => [...cell.matchAll(/`((?:[a-z][a-z-]*\/)?response\/(?:(?:[a-z][a-z-]*\/)*[A-Za-z0-9_<>.-]+\.md|data\/[A-Za-z0-9_<>./-]+|artifacts\/[A-Za-z0-9_<>./-]+|response\.json))`/g)].map((m) => m[1]);
+export const exchangeOf = (file) => { const m = /^([a-z][a-z-]*)\/response\//.exec(file); return m ? m[1] : null; };
+export const isYes = (cell) => YES.has(strip(cell).trim().toLowerCase());
+export const kindOf = (cell) => strip(cell.trim());
+
+export async function loadOperatorPackages(root) {
+  const { readdir } = await import('node:fs/promises');
+  const { existsSync } = await import('node:fs');
+  const dir = path.join(root, 'operators');
+  const out = [];
+  for (const entry of (await readdir(dir, { withFileTypes: true })).filter((e) => e.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
+    const full = path.join(dir, entry.name);
+    const manifest = JSON.parse(await readFile(path.join(full, 'operator.json'), 'utf8'));
+    const mdPath = path.join(full, 'operator.md');
+    if (!existsSync(mdPath)) { out.push({ dir: full, name: entry.name, manifest, shape: 'v8' }); continue; }
+    const en = parseOperatorMd(await readFile(mdPath, 'utf8'), 'en');
+    const viPath = path.join(full, 'operator.vi.md');
+    const vi = existsSync(viPath) ? parseOperatorMd(await readFile(viPath, 'utf8'), 'vi') : null;
+    out.push({ dir: full, name: entry.name, manifest, shape: 'v9', en, vi });
+  }
+  return out;
+}

package/scripts/run-operator-self-tests.mjs

@@ -0,0 +1,36 @@
+import { readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+
+const run = promisify(execFile);
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const operators = path.join(root, 'operators');
+const failures = [];
+let passed = 0;
+
+for (const entry of await readdir(operators, { withFileTypes: true })) {
+  if (!entry.isDirectory()) continue;
+  const selfTest = path.join(operators, entry.name, 'self-test.mjs');
+  if (!existsSync(selfTest)) {
+    failures.push(`${entry.name}: no self-test.mjs`);
+    continue;
+  }
+  try {
+    const { stdout } = await run(process.execPath, [selfTest], { cwd: path.join(operators, entry.name) });
+    process.stdout.write(stdout);
+    passed += 1;
+  } catch (error) {
+    failures.push(`${entry.name}: ${(error.stderr || error.message).trim()}`);
+  }
+}
+
+if (failures.length > 0) {
+  process.stderr.write(`${failures.join('\n')}\n`);
+  process.exitCode = 1;
+} else {
+  process.stdout.write(`${passed} operator self-tests passed\n`);
+}

package/scripts/validate-alias.mjs

@@ -0,0 +1,165 @@
+// Every reference an operator reads is named by an alias that alias/alias.json resolves to an exact
+// location. An operator declares its aliases in operator.json (`refs`), and its context.md states
+// the same table for the reader. This script rejects an alias nobody registered, a required alias
+// the context table omits, a writer that is not an operator, and a context row that names an alias
+// the operator did not declare. Disk existence is not checked here: most locations are
+// machine-local (`.worktrees`, `.workspaces/local`) and absent on a fresh clone by design.
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { loadAliasRegistry, baseOf as baseOfIn } from './alias-registry.mjs';
+import { parseOperatorMd, cellAliases, isYes } from './operator-md.mjs';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const registry = await loadAliasRegistry(root);
+const errors = [];
+
+if (registry.schemaVersion !== 8) errors.push('alias.json: schemaVersion must be 8');
+const aliases = registry.aliases ?? {};
+const KINDS = new Set(['file', 'dir', 'checkout', 'service', 'caller-supplied', 'tool']);
+for (const [alias, def] of Object.entries(aliases)) {
+  if (!/^@[a-z][a-z-]*(?:\/[a-z_][a-z0-9_-]*)*$/.test(alias)) errors.push(`alias.json: alias ${alias} must look like @name or @name/sub/path`);
+  for (const key of ['params', 'kind', 'resolvesTo', 'scheme', 'bind', 'writers', 'purpose']) {
+    if (def[key] === undefined) errors.push(`alias.json: ${alias} lacks ${key}`);
+  }
+  if (!KINDS.has(def.kind)) errors.push(`alias.json: ${alias} kind ${def.kind} is not one of ${[...KINDS].join(', ')}`);
+  for (const p of def.params ?? []) {
+    if (!def.resolvesTo.includes(`<${p}>`) && !def.resolvesTo.includes(`${p}/`) && !def.resolvesTo.includes(`/${p}`)) {
+      errors.push(`alias.json: ${alias} declares param ${p} that resolvesTo never uses`);
+    }
+  }
+}
+
+const operatorsDir = path.join(root, 'operators');
+const operatorIds = new Set();
+const manifests = [];
+for (const entry of await readdir(operatorsDir, { withFileTypes: true })) {
+  if (!entry.isDirectory()) continue;
+  const dir = path.join(operatorsDir, entry.name);
+  const manifest = JSON.parse(await readFile(path.join(dir, 'operator.json'), 'utf8'));
+  operatorIds.add(manifest.id);
+  manifests.push({ dir, manifest });
+}
+for (const [alias, def] of Object.entries(aliases)) {
+  for (const w of def.writers ?? []) {
+    if (w !== '*' && !operatorIds.has(w)) errors.push(`alias.json: ${alias} names writer ${w}, which is not an operator`);
+  }
+}
+
+// A context table row: | `@alias/...` | resolves to | bind | Required/Optional |
+const ROW = /^\|\s*`(@[a-z][a-z-]*(?:\/[A-Za-z0-9_<>.@#:-]+)*)`\s*\|/;
+// The registered alias an alias string belongs to is its longest registered prefix.
+const baseOf = (alias) => baseOfIn(aliases, alias);
+function tableAliases(text, heading) {
+  const lines = text.split(/\r?\n/);
+  const start = lines.findIndex((l) => l.trim() === heading);
+  if (start === -1) return null;
+  const out = [];
+  for (let i = start + 1; i < lines.length && !lines[i].startsWith('## '); i += 1) {
+    const m = ROW.exec(lines[i]);
+    if (m) out.push(m[1]);
+  }
+  return out;
+}
+
+// An operator.md package declares its aliases in the Context table and routes by them in the Steps
+// table; both languages are checked. Dynamic inputs are kinds, not aliases, so the @dynamic rule of
+// the old shape does not apply.
+async function checkOperatorMd(dir, id) {
+  let count = 0;
+  const seen = new Set();
+  const en = parseOperatorMd(await readFile(path.join(dir, 'operator.md'), 'utf8'), 'en');
+  const rows = en.tables.context?.rows ?? [];
+  if (rows.length === 0) { errors.push(`${id}: operator.md Context table is empty`); return 0; }
+  const declaredBases = new Set();
+  const requiredBases = new Set();
+  for (const row of rows) {
+    const alias = cellAliases(row.alias)[0];
+    if (!alias) { errors.push(`${id}: operator.md Context row "${row.alias}" names no alias`); continue; }
+    const base = baseOf(alias);
+    if (!base) errors.push(`${id}: ref ${alias} is not registered in alias/alias.json`);
+    if (seen.has(alias)) errors.push(`${id}: ref ${alias} is declared twice`);
+    seen.add(alias);
+    if (base) { declaredBases.add(base); if (isYes(row.required)) requiredBases.add(base); }
+    count += 1;
+  }
+  // @tools/<id> in a Steps cell is a call, not a read: it must be declared in operator.json → resources.tools.
+  const manifest = JSON.parse(await readFile(path.join(dir, 'operator.json'), 'utf8'));
+  const declaredTools = new Set(Object.keys(manifest.resources?.tools ?? {}));
+  for (const [file, lang] of [['operator.md', 'en'], ['operator.vi.md', 'vi']]) {
+    if (!existsSync(path.join(dir, file))) continue;
+    const op = lang === 'en' ? en : parseOperatorMd(await readFile(path.join(dir, file), 'utf8'), 'vi');
+    const used = new Set();
+    const toolsUsed = new Set();
+    for (const step of op.tables.steps?.rows ?? []) for (const a of [...cellAliases(step.reads), ...cellAliases(step.writes)]) {
+      if (a.startsWith('@dynamic')) { errors.push(`${id}: ${file} step ${step.n} names ${a}; an operator.md package passes dynamic files as kinds, not aliases`); continue; }
+      if (a.startsWith('@tools/')) { toolsUsed.add(a); if (!aliases[a]) errors.push(`${id}: ${file} step ${step.n} names ${a}, which resources/tools.json does not define`); else if (!declaredTools.has(a)) errors.push(`${id}: ${file} step ${step.n} calls ${a}, which operator.json resources.tools does not declare`); continue; }
+      used.add(baseOf(a) ?? a);
+    }
+    if (lang === 'en') for (const t of declaredTools) if (!toolsUsed.has(t) && t !== '@tools/fileread') errors.push(`${id}: operator.json declares ${t} but no step names it`);
+    for (const u of used) if (!declaredBases.has(u)) errors.push(`${id}: ${file} Steps read or write ${u}, which the Context table does not declare`);
+    for (const r of requiredBases) if (!used.has(r)) errors.push(`${id}: ${file} Steps never read or write required ${r}`);
+    if (used.size === 0) errors.push(`${id}: ${file} Steps name no alias at all`);
+  }
+  return count;
+}
+
+let declared = 0;
+for (const { dir, manifest } of manifests) {
+  const id = manifest.id;
+  if (existsSync(path.join(dir, 'operator.md'))) { declared += await checkOperatorMd(dir, id); continue; }
+  const refs = manifest.refs;
+  if (!Array.isArray(refs) || refs.length === 0) { errors.push(`${id}: operator.json must declare refs`); continue; }
+  const seen = new Set();
+  for (const ref of refs) {
+    const base = baseOf(ref.alias ?? '');
+    if (!base) errors.push(`${id}: ref ${ref.alias} is not registered in alias/alias.json`);
+    if (typeof ref.required !== 'boolean') errors.push(`${id}: ref ${ref.alias} must say required true or false`);
+    if (typeof ref.purpose !== 'string' || ref.purpose.length === 0) errors.push(`${id}: ref ${ref.alias} needs a purpose`);
+    if (seen.has(ref.alias)) errors.push(`${id}: ref ${ref.alias} is declared twice`);
+    seen.add(ref.alias);
+    declared += 1;
+  }
+  if (!refs.some((r) => r.alias.startsWith('@dynamic/') && r.required)) {
+    errors.push(`${id}: a required @dynamic/<file> ref is missing; every step writes its receipt there`);
+  }
+  // execute.md routes by alias: every @alias in the Sequence table's Reads/Writes cells must be a
+  // declared ref, and every required ref must be read or written by some step. A step that names a
+  // location the operator never declared is how an agent wanders outside its region.
+  for (const [file, heading] of [['execute.md', '## Sequence'], ['execute.vi.md', '## Trình tự']]) {
+    const text = await readFile(path.join(dir, file), 'utf8');
+    const lines = text.split(/\r?\n/);
+    const start = lines.findIndex((l) => l.trim() === heading);
+    if (start === -1) { errors.push(`${id}: ${file} has no ${heading} section`); continue; }
+    const used = new Set();
+    for (let i = start + 1; i < lines.length && !lines[i].startsWith('## '); i += 1) {
+      const cells = lines[i].split('|').map((c) => c.trim());
+      if (cells.length < 6 || !/^\d+$/.test(cells[1])) continue;
+      for (const cell of [cells[3], cells[4]]) for (const m of cell.matchAll(/@[a-z][a-z-]*(?:\/[A-Za-z0-9_<>.@#:-]+)*/g)) { const b = baseOf(m[0]); used.add(b ?? m[0]); }
+    }
+    const declaredBases = new Set(refs.map((r) => baseOf(r.alias)));
+    for (const u of used) if (!declaredBases.has(u)) errors.push(`${id}: ${file} Sequence reads or writes ${u}, which operator.json does not declare`);
+    for (const r of refs) {
+      const b = baseOf(r.alias);
+      if (r.required && !used.has(b)) errors.push(`${id}: ${file} Sequence never reads or writes required ${r.alias}`);
+    }
+    if (used.size === 0) errors.push(`${id}: ${file} Sequence names no alias at all`);
+  }
+  for (const [file, heading] of [['context.md', '## Refs'], ['context.vi.md', '## Ref']]) {
+    const text = await readFile(path.join(dir, file), 'utf8');
+    const rows = tableAliases(text, heading);
+    if (rows === null) { errors.push(`${id}: ${file} has no ${heading} section`); continue; }
+    const declaredAliases = new Set(refs.map((r) => r.alias));
+    for (const r of refs) if (r.required && !rows.includes(r.alias)) errors.push(`${id}: ${file} ${heading} table omits required ${r.alias}`);
+    for (const row of rows) if (!declaredAliases.has(row)) errors.push(`${id}: ${file} ${heading} table names ${row}, which operator.json does not declare`);
+  }
+}
+
+if (errors.length > 0) {
+  process.stderr.write(`${errors.join('\n')}\n`);
+  process.exitCode = 1;
+} else {
+  process.stdout.write(`alias closed: ${Object.keys(aliases).length} aliases, ${declared} bindings across ${manifests.length} operators\n`);
+}

package/scripts/validate-defaults.mjs

@@ -0,0 +1,72 @@
+// A request made only of an operator's own defaults must pass validate-request. This is the static
+// half of "the tables agree with the gates": every Requirements row whose Default is not — is turned
+// into a value, every required Input is pointed at a placeholder file, the request is written into a
+// throwaway session, and validate-request judges it. A Default the gate cannot accept, or a required
+// field the orchestrator could never fill, fails here instead of in a real session.
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+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 { validateRequest, isRequiredField } from './validate-request.mjs';
+
+const unquote = (s) => String(s ?? '').trim().replace(/^`|`$/g, '');
+const head = 'a'.repeat(40);
+
+// A Default cell is prose for a person; the orchestrator turns it into a value of the field's Type.
+function valueFor(row) {
+  const d = unquote(row.default).trim();
+  const type = row.type.trim().toLowerCase();
+  if (isRequiredField(row)) {
+    if (type.startsWith('number')) return 1;
+    if (type.startsWith('list')) return ['placeholder'];
+    if (type.startsWith('choice')) { const m = /\(([^)]+)\)/.exec(row.type) || /(\w+(?:\s*\|\s*\w+)+)/.exec(row.ask ?? ''); return m ? m[1].split(/\s*\|\s*/)[0].trim() : 'placeholder'; }
+    return 'placeholder';
+  }
+  if (d === 'null' || d === 'none' && type === 'token') return null;
+  if (/^\d+$/.test(d)) return Number(d);
+  if (type.startsWith('list')) return d === '[]' || d === 'empty' || d === 'rỗng' ? [] : d.split(',').map((s) => s.trim());
+  if (d === '[]') return [];
+  return d;
+}
+
+export async function validateDefaults(root) {
+  const errors = [];
+  const packages = (await loadOperatorPackages(root)).filter((p) => p.shape === 'v9');
+  const session = mkdtempSync(path.join(tmpdir(), 'defaults-'));
+  try {
+    let n = 0;
+    for (const pkg of packages) {
+      const op = pkg.en;
+      n += 1;
+      const branch = path.join(session, `step-${n}`, 'parallel-1');
+      mkdirSync(path.join(branch, 'request'), { recursive: true });
+      const requirements = {};
+      for (const row of op.tables.requirements?.rows ?? []) requirements[unquote(row.field)] = valueFor(row);
+      const inputs = {};
+      for (const row of op.tables.inputs?.rows ?? []) {
+        if (!isYes(row.required)) continue;
+        const kind = kindOf(row.kind);
+        const producer = path.join(session, 'step-0', 'parallel-1', 'response');
+        mkdirSync(path.join(producer, 'data'), { recursive: true });
+        const file = `step-0/parallel-1/response/${kind}.md`;
+        writeFileSync(path.join(session, file), `# ${kind}\n`);
+        inputs[kind] = file;
+      }
+      const contexts = [];
+      for (const row of op.tables.context?.rows ?? []) { const a = cellAliases(row.alias)[0]; if (a) contexts.push({ alias: a.replace(/<[^>]+>/g, 'x'), head: a.startsWith('@workspaces/') ? head : null }); }
+      const request = { schemaVersion: 9, operatorId: pkg.manifest.id, step: n, parallel: 1, sessionId: 'defaults', contexts, requirements, inputs, resume: null };
+      writeFileSync(path.join(branch, 'request', 'request.json'), JSON.stringify(request, null, 2));
+      const { errors: e } = await validateRequest(root, branch, packages);
+      for (const line of e) errors.push(`${pkg.manifest.id}: defaults-only request rejected: ${line}`);
+    }
+  } finally { rmSync(session, { recursive: true, force: true }); }
+  return { errors, count: packages.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 validateDefaults(root);
+  if (errors.length) { process.stderr.write(`${errors.join('\n')}\n`); process.exitCode = 1; } else process.stdout.write(`defaults closed: ${count} operators accept a defaults-only request\n`);
+}

package/scripts/validate-knowledge-citations.mjs

@@ -0,0 +1,90 @@
+// Every rule identifier a knowledge file cites must be one the knowledge tree publishes.
+//
+// A rule exists only as a `## PREFIX-n — …` heading in a canonical English knowledge file. This
+// script builds that inventory, then scans every canonical knowledge file for citations of the shape
+// `PREFIX-n` or `PREFIX-a..b` and rejects any that resolve to nothing: a number the topic never
+// published, a range that runs past the inventory, or a prefix no file owns. The `.vi.md` mirrors
+// are scanned too, because a mirror that cites a rule the English file does not is drift.
+//
+// Why this exists: `grammars/starci` cited `TONE-4..5`, `RENDER-TRUTH-1..4`, and `GAP-1..5` against a
+// tree that publishes `TONE-1..3`, `TRUTH-1..4`, and `GAP-0..6`. Nothing failed, so nobody noticed.
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'knowledge');
+
+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()) out.push(...(await walk(full)));
+    else if (entry.name.endsWith('.md')) out.push(full);
+  }
+  return out;
+}
+
+const files = (await walk(root)).sort();
+const canonical = files.filter((f) => !f.endsWith('.vi.md'));
+
+// Inventory: one heading per published rule. Prefixes may contain hyphens (CONTROL-STATE, CORE-SURFACE).
+// A prefix may carry digits (A11Y); the trailing number is always the ordinal.
+const HEADING = /^## ([A-Z][A-Z0-9]*(?:-[A-Z][A-Z0-9]*)*)-(\d+)\b/;
+const published = new Map(); // prefix -> Set(number)
+const ownerOf = new Map(); // prefix -> file
+for (const file of canonical) {
+  const text = await readFile(file, 'utf8');
+  for (const line of text.split(/\r?\n/)) {
+    const m = HEADING.exec(line);
+    if (!m) continue;
+    const [, prefix, n] = m;
+    if (!published.has(prefix)) {
+      published.set(prefix, new Set());
+      ownerOf.set(prefix, path.relative(root, file));
+    }
+    published.get(prefix).add(Number(n));
+  }
+}
+
+// Citations: PREFIX-n or PREFIX-a..b, where PREFIX is a published prefix or looks like one.
+// Tokens whose prefix is unknown are reported once per file so a fabricated family cannot hide.
+const CITATION = /\b([A-Z][A-Z0-9]*(?:-[A-Z][A-Z0-9]*)*)-(\d+)(?:\.\.(\d+))?\b/g;
+const IGNORE_PREFIXES = new Set(['SHA', 'UTF', 'ISO', 'RFC', 'HTTP', 'ES', 'V', 'H', 'CVE', 'X', 'GPT']);
+const errors = [];
+for (const file of files) {
+  const rel = path.relative(root, file);
+  const text = await readFile(file, 'utf8');
+  const lines = text.split(/\r?\n/);
+  lines.forEach((line, i) => {
+    if (HEADING.test(line)) return; // the heading is the publication, not a citation
+    // A file may name the numbers it retired, so a reader knows they are not free. Such a line
+    // says "retired" (or its mirror "đã nghỉ") and may cite unpublished numbers of a published
+    // prefix; it still may not cite a prefix nobody owns.
+    const retiredLine = /retired|đã nghỉ/i.test(line);
+    for (const m of line.matchAll(CITATION)) {
+      const [, prefix, a, b] = m;
+      if (IGNORE_PREFIXES.has(prefix)) continue;
+      const set = published.get(prefix);
+      if (!set) {
+        errors.push(`${rel}:${i + 1}: prefix ${prefix} is published by no knowledge file (${m[0]})`);
+        continue;
+      }
+      if (retiredLine) continue;
+      const from = Number(a);
+      const to = b === undefined ? from : Number(b);
+      if (to < from) errors.push(`${rel}:${i + 1}: inverted range ${m[0]}`);
+      for (let n = from; n <= to; n += 1) {
+        if (!set.has(n)) errors.push(`${rel}:${i + 1}: ${prefix}-${n} is not published (${ownerOf.get(prefix)} publishes ${[...set].sort((x, y) => x - y).join(',')})`);
+      }
+    }
+  });
+}
+
+if (errors.length > 0) {
+  process.stderr.write(`${errors.join('\n')}\n`);
+  process.exitCode = 1;
+} else {
+  const total = [...published.values()].reduce((n, s) => n + s.size, 0);
+  process.stdout.write(`knowledge citations closed: ${published.size} prefixes, ${total} rules, ${files.length} files\n`);
+}