@vegastack/vegafactory 0.19.0

package/skill/skillify/scripts/scaffold-skill.mjs

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+// Scaffold a new skill tree at skills/<name>/ (or skills/<group>/<name>/) from skillify's
+// templates.
+//
+//   node scripts/scaffold-skill.mjs <skill-name> --dir <repo-root> [--group <group>] [--write] [--json]
+//
+// --group places the skill in an existing group. Creating a group is skill-maintainer's job
+// (packages/cli/scripts/structure.mjs create-group), so an unknown group is refused rather than
+// invented: a mistyped group must never bring a stray family into existence.
+//
+// Dry-run by default: prints the plan (files that would be created plus the
+// wiring actions that would be performed) and creates nothing. --write stages
+// the tree in a temporary sibling inside skills/ and renames it into place,
+// refusing existing directories and symlinks, then performs the repo wiring
+// itself: packaging.json entry, root README row, changeset. Exit codes: 0 ok,
+// 1 refusal or failure, 2 usage error.
+import { lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const templatesRoot = resolve(here, '..', 'assets', 'templates')
+
+// Template file -> output path inside the skill (null = tests/<name>.test.ts).
+export const templateFiles = [
+  ['SKILL.md.template', 'SKILL.md'],
+  ['README.md.template', 'README.md'],
+  ['sources.json.template', 'refresh/sources.json'],
+  ['REFRESH.md.template', 'refresh/REFRESH.md'],
+  ['openai.yaml.template', 'agents/openai.yaml'],
+  // One placeholder case; the structure check warns until real cases replace it (skillify Phase 4).
+  ['evals.json.template', 'evals/evals.json'],
+  // Scaffolded empty so the shape test stays red until real queries are written.
+  ['trigger-queries.json.template', 'tests/fixtures/trigger-queries.json'],
+  ['skill.test.ts.template', null],
+]
+
+// The scaffolded files that ship to installers (README and tests never package).
+const defaultPackagedFiles = ['SKILL.md', 'agents/openai.yaml', 'refresh/REFRESH.md', 'refresh/sources.json']
+
+// Full grammar shared by the repo validator and every target harness: starts
+// with a lowercase letter, then lowercase letters/digits/hyphens, no
+// consecutive hyphens, no trailing hyphen, at most 64 characters.
+export function validateName(name) {
+  if (typeof name !== 'string' || name.length === 0) return 'skill name is required'
+  if (name.length > 64) return `name is ${name.length} characters; the maximum is 64`
+  if (!/^[a-z]/.test(name)) return 'name must start with a lowercase letter'
+  if (!/^[a-z0-9-]+$/.test(name)) return 'name may contain only lowercase letters, digits, and hyphens'
+  if (name.includes('--')) return 'name must not contain consecutive hyphens'
+  if (name.endsWith('-')) return 'name must not end with a hyphen'
+  return null
+}
+
+// This script ships inside the skillify skill, so it must stay dependency-free and cannot import
+// the repo's lib/skills.mjs. Deliberate small duplication of its GROUP.md title read; the two are
+// kept honest by structure.mjs check, which fails when the README and GROUP.md disagree.
+export function groupTitle(markdown) {
+  const lines = markdown.split('\n')
+  const headingIndex = lines.findIndex(line => /^#\s+\S/.test(line))
+  if (headingIndex === -1) return null
+  const title = lines[headingIndex].replace(/^#\s+/, '').trim()
+  const blurb = lines.slice(headingIndex + 1).find(line => line.trim() !== '')?.trim()
+  if (!title || !blurb || blurb.startsWith('#')) return null
+  return title
+}
+
+// Two-level scan mirroring lib/skills.mjs's discovery. Duplicated for the same reason as
+// groupTitle: this script ships inside the skillify skill and cannot import repo tooling.
+async function findSkillAnywhere(skillsRoot, name) {
+  if ((await entryAt(join(skillsRoot, name, 'SKILL.md')))?.isFile()) return join(skillsRoot, name)
+  for (const entry of await readdir(skillsRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue
+    const path = join(skillsRoot, entry.name, name)
+    if ((await entryAt(join(path, 'SKILL.md')))?.isFile()) return path
+  }
+  return null
+}
+
+async function entryAt(path) {
+  try {
+    return await lstat(path)
+  } catch {
+    return null
+  }
+}
+
+async function writeAtomic(path, body) {
+  const staging = `${path}.scaffold-tmp`
+  await writeFile(staging, body)
+  await rename(staging, path)
+}
+
+// Adds the new skill's entry to packages/cli/packaging.json with the default
+// scaffolded runtime files. Extra authored files added later must be appended
+// there by hand — sync-skill.mjs still fails loudly on anything unlisted.
+async function wirePackaging(repoRoot, name, write) {
+  const path = join(repoRoot, 'packages/cli/packaging.json')
+  if (!(await entryAt(path))?.isFile()) return { step: 'packaging.json entry', status: 'skipped: packages/cli/packaging.json not found' }
+  const packaged = JSON.parse(await readFile(path, 'utf8'))
+  if (name in packaged) return { step: 'packaging.json entry', status: 'skipped: entry already exists' }
+  if (!write) return { step: 'packaging.json entry', status: 'planned' }
+  packaged[name] = defaultPackagedFiles
+  const sorted = Object.fromEntries(Object.keys(packaged).sort().map(key => [key, packaged[key]]))
+  await writeAtomic(path, `${JSON.stringify(sorted, null, 2)}\n`)
+  return { step: 'packaging.json entry', status: 'done' }
+}
+
+// Resolves where a row belongs: the end of the ungrouped table, or of the table under the
+// group's "### <title>" section. Both windows are bounded by the "## Skills" region, so a row can
+// never land in a neighbouring family's table or in an unrelated table elsewhere in the README.
+// Returns null when the README has no usable table, so callers can refuse before writing rather
+// than report a "skipped:" success afterwards.
+export function findRowInsertion(lines, group, groupHeading) {
+  const regionStart = lines.findIndex(line => /^##\s+Skills\s*$/.test(line))
+  if (regionStart < 0) return null
+  const afterRegion = lines.findIndex((line, index) => index > regionStart && /^##\s+/.test(line) && !/^###/.test(line))
+  const regionEnd = afterRegion < 0 ? lines.length : afterRegion
+
+  let from = regionStart
+  let to = regionEnd
+  if (group) {
+    from = lines.findIndex((line, index) => index > regionStart && index < regionEnd && line.trim() === `### ${groupHeading}`)
+    if (from < 0) return { missingSection: true }
+    const next = lines.findIndex((line, index) => index > from && index < regionEnd && /^###\s+/.test(line))
+    to = next < 0 ? regionEnd : next
+  } else {
+    const firstSection = lines.findIndex((line, index) => index > regionStart && index < regionEnd && /^###\s+/.test(line))
+    if (firstSection >= 0) to = firstSection
+  }
+
+  const header = lines.findIndex((line, index) => index >= from && index < to && /^\| *Skill *\|/.test(line))
+  if (header < 0 || !/^\|[ -]*---/.test(lines[header + 1] ?? '')) return null
+  let last = header + 1
+  while (last + 1 < to && lines[last + 1]?.startsWith('|')) last += 1
+  return { index: last }
+}
+
+async function wireReadme(repoRoot, name, group, groupHeading, write) {
+  const path = join(repoRoot, 'README.md')
+  if (!(await entryAt(path))?.isFile()) return { step: 'root README row', status: 'skipped: README.md not found' }
+  const body = await readFile(path, 'utf8')
+  const relativePath = group ? `${group}/${name}` : name
+  if (body.includes(`](skills/${relativePath}/)`)) return { step: 'root README row', status: 'skipped: row already exists' }
+  const lines = body.split('\n')
+
+  const target = findRowInsertion(lines, group, groupHeading)
+  if (target?.missingSection) throw new Error(`README.md has no "### ${groupHeading}" section for group "${group}" - create it with structure.mjs create-group`)
+  if (!target) return { step: 'root README row', status: 'skipped: Skills table not found' }
+  const last = target.index
+  if (!write) return { step: 'root README row', status: 'planned' }
+  const row = `| [${name}](skills/${relativePath}/) | TODO: one-line description | [Walkthrough](skills/${relativePath}/README.md) · [SKILL.md](skills/${relativePath}/SKILL.md) |`
+  lines.splice(last + 1, 0, row)
+  await writeAtomic(path, lines.join('\n'))
+  return { step: 'root README row', status: 'done' }
+}
+
+// Writes the changeset introducing the skill (content versioning: new skill = minor).
+async function wireChangeset(repoRoot, name, write) {
+  const directory = join(repoRoot, '.changeset')
+  if (!(await entryAt(directory))?.isDirectory()) return { step: 'changeset', status: 'skipped: .changeset/ not found' }
+  const path = join(directory, `add-${name}.md`)
+  if (await entryAt(path)) return { step: 'changeset', status: 'skipped: changeset already exists' }
+  if (!write) return { step: 'changeset', status: 'planned' }
+  await writeAtomic(path, `---\n"@vegastack/vegafactory": minor\n---\n\nAdd the ${name} skill.\n`)
+  return { step: 'changeset', status: 'done' }
+}
+
+export async function wireSkill({ name, repoRoot, group = null, groupHeading = null, write = false }) {
+  // groupHeading is an optimisation for scaffoldSkill, which has already read GROUP.md. A caller
+  // using the documented { name, repoRoot, group, write } shape gets it derived here rather than
+  // a row addressed to "### null".
+  if (group && !groupHeading) {
+    const doc = await entryAt(join(repoRoot, 'skills', group, 'GROUP.md'))
+    if (!doc?.isFile()) throw new Error(`Group "${group}" has no GROUP.md - every group carries one`)
+    groupHeading = groupTitle(await readFile(join(repoRoot, 'skills', group, 'GROUP.md'), 'utf8'))
+    if (!groupHeading) throw new Error(`skills/${group}/GROUP.md is malformed - it needs an H1 title followed by one non-empty blurb line`)
+  }
+  return [
+    await wirePackaging(repoRoot, name, write),
+    await wireReadme(repoRoot, name, group, groupHeading, write),
+    await wireChangeset(repoRoot, name, write),
+  ]
+}
+
+export async function scaffoldSkill({ name, dir, group = null, write = false, now = new Date() }) {
+  const nameError = validateName(name)
+  if (nameError) throw new Error(`Invalid skill name ${JSON.stringify(name ?? null)}: ${nameError}`)
+  if (!dir) throw new Error('--dir <repo-root> is required')
+  const repoRoot = resolve(dir)
+  const skillsRoot = join(repoRoot, 'skills')
+  const skillsEntry = await entryAt(skillsRoot)
+  // lstat does not follow symlinks, so a symlinked skills/ fails isDirectory().
+  if (!skillsEntry || !skillsEntry.isDirectory()) {
+    throw new Error(`${skillsRoot} is not a real directory - point --dir at the vegafactory repo root`)
+  }
+
+  // A group must already exist and carry a well-formed GROUP.md; creating one is
+  // skill-maintainer's structure.mjs create-group, never a side effect of scaffolding a skill.
+  let groupHeading = null
+  if (group) {
+    const groupError = validateName(group)
+    if (groupError) throw new Error(`Invalid group name ${JSON.stringify(group)}: ${groupError}`)
+    const groupRoot = join(skillsRoot, group)
+    const groupEntry = await entryAt(groupRoot)
+    if (!groupEntry || !groupEntry.isDirectory()) {
+      throw new Error(`Group "${group}" does not exist at ${groupRoot} - create it first with: node packages/cli/scripts/structure.mjs create-group ${group} --title <title> --blurb <blurb> --write`)
+    }
+    const groupDoc = await entryAt(join(groupRoot, 'GROUP.md'))
+    if (!groupDoc?.isFile()) throw new Error(`Group "${group}" has no GROUP.md - every group carries one; see skill-maintainer's group workflow`)
+    groupHeading = groupTitle(await readFile(join(groupRoot, 'GROUP.md'), 'utf8'))
+    if (!groupHeading) throw new Error(`skills/${group}/GROUP.md is malformed - it needs an H1 title followed by one non-empty blurb line`)
+  }
+
+  const parent = group ? join(skillsRoot, group) : skillsRoot
+  const target = join(parent, name)
+  if (await entryAt(target)) throw new Error(`Refusing to scaffold: ${target} already exists`)
+
+  // Skill names are unique across the whole tree, not just within one directory: the packaged
+  // bundle is flat, so a duplicate at the other depth would break the next build. Checked here,
+  // before anything is written, rather than left to that build.
+  const clash = await findSkillAnywhere(skillsRoot, name)
+  if (clash) throw new Error(`Refusing to scaffold: a skill named "${name}" already exists at ${clash} - the packaged bundle is flat, so skill names are unique across the whole tree`)
+
+  // Every refusal belongs in this pre-flight. wireReadme runs after the tree is renamed into
+  // place and the packaging entry written, so anything discovered there would leave a half-wired
+  // skill on disk while reporting a refusal - or, worse, report success with no row at all.
+  // Both wiring targets a scaffolded skill cannot do without must therefore be resolvable BEFORE
+  // the tree is staged: an absent one is a refusal, not a `skipped:` status, because a skill with
+  // no README row or no packaging entry is exactly the state structure.mjs check blocks. Only
+  // `.changeset/` still degrades to `skipped:` - a missing changeset breaks no check.
+  const readmePath = join(repoRoot, 'README.md')
+  if (!(await entryAt(readmePath))?.isFile()) {
+    throw new Error(`README.md not found at ${readmePath} - every skill needs its Skills-table row, so refusing rather than scaffolding a skill the structure check would block`)
+  }
+  const lines = (await readFile(readmePath, 'utf8')).split('\n')
+  const rowTarget = findRowInsertion(lines, group, groupHeading)
+  if (rowTarget?.missingSection) {
+    throw new Error(`README.md has no "### ${groupHeading}" section for group "${group}" - create it with structure.mjs create-group`)
+  }
+  if (!rowTarget) {
+    throw new Error(`README.md has no ${group ? `table under "### ${groupHeading}"` : 'ungrouped Skills table'} to add a row to - every skill needs its row, so refusing rather than scaffolding a skill the structure check would block`)
+  }
+
+  const packagingPath = join(repoRoot, 'packages/cli/packaging.json')
+  if (!(await entryAt(packagingPath))?.isFile()) {
+    throw new Error(`packages/cli/packaging.json not found at ${packagingPath} - every skill needs its packaging entry, so refusing rather than scaffolding a skill the structure check would block`)
+  }
+
+  // The generated test imports the repo validator by relative path, so its depth follows the
+  // skill's: skills/<name>/tests/ is three levels up, skills/<group>/<name>/tests/ is four.
+  const validatorPath = `${group ? '../../../..' : '../../..'}/packages/cli/scripts/validate-skill.mjs`
+  // Only a grouped skill gets the family-install block; an ungrouped one would otherwise ship a
+  // command naming a group that does not exist. It is its own fence, not a second line in the
+  // first one: pasting a shared fence would run the alternative too.
+  const groupInstallBlock = group
+    ? `\nOr the whole ${group} family at once:\n\n\`\`\`sh\nnpx @vegastack/vegafactory skills add --group ${group} --global\n\`\`\`\n`
+    : ''
+
+  const outputs = templateFiles.map(([source, output]) => [source, output ?? `tests/${name}.test.ts`])
+  const plan = { name, group, target, files: outputs.map(([, output]) => output), wrote: false }
+  if (!write) return { ...plan, wiring: await wireSkill({ name, repoRoot, group, groupHeading }) }
+
+  const date = now.toISOString().slice(0, 10)
+  const staging = await mkdtemp(join(parent, `.${name}.scaffold-`))
+  try {
+    for (const [source, output] of outputs) {
+      const body = await readFile(join(templatesRoot, source), 'utf8')
+      const rendered = body
+        .replaceAll('{{name}}', name)
+        .replaceAll('{{date}}', date)
+        .replaceAll('{{validatorPath}}', validatorPath)
+        .replaceAll('{{groupInstallBlock}}', groupInstallBlock)
+      const destination = join(staging, output)
+      await mkdir(dirname(destination), { recursive: true })
+      await writeFile(destination, rendered)
+    }
+    if (await entryAt(target)) throw new Error(`Refusing to scaffold: ${target} already exists`)
+    await rename(staging, target)
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true })
+    throw error
+  }
+  return { ...plan, wrote: true, wiring: await wireSkill({ name, repoRoot, group, groupHeading, write: true }) }
+}
+
+function parseArguments(argv) {
+  const options = { name: undefined, dir: undefined, group: null, write: false, json: false }
+  const rest = [...argv]
+  while (rest.length) {
+    const flag = rest.shift()
+    if (flag === '--dir') {
+      const value = rest.shift()
+      if (value === undefined || value.startsWith('-')) throw new Error('--dir requires a value')
+      options.dir = value
+    } else if (flag === '--group') {
+      const value = rest.shift()
+      if (value === undefined || value.startsWith('-')) throw new Error('--group requires a value')
+      options.group = value
+    } else if (flag === '--write') options.write = true
+    else if (flag === '--json') options.json = true
+    else if (flag.startsWith('-')) throw new Error(`Unknown option: ${flag}`)
+    else if (options.name === undefined) options.name = flag
+    else throw new Error(`Unexpected argument: ${flag}`)
+  }
+  if (!options.name || !options.dir) {
+    throw new Error('Usage: node scripts/scaffold-skill.mjs <skill-name> --dir <repo-root> [--group <group>] [--write] [--json]')
+  }
+  return options
+}
+
+const invokedDirectly = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+if (invokedDirectly) {
+  let options
+  try {
+    options = parseArguments(process.argv.slice(2))
+  } catch (error) {
+    console.error(String(error.message ?? error))
+    process.exit(2)
+  }
+  try {
+    const result = await scaffoldSkill(options)
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2))
+    } else {
+      console.log(result.wrote ? `Created ${result.target}` : `Dry run - pass --write to create ${result.target}`)
+      for (const file of result.files) console.log(`  ${file}`)
+      console.log('Wiring:')
+      for (const { step, status } of result.wiring) console.log(`  - ${step}: ${status}`)
+    }
+  } catch (error) {
+    console.error(String(error.message ?? error))
+    process.exit(1)
+  }
+}

package/skill/skillify/scripts/trigger-check.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+// skillify guard: deterministic family-level check over every authored skill's
+// tests/fixtures/trigger-queries.json. Two skills claiming the same normalised
+// query as should_trigger:true without naming each other in ambiguous_with is a
+// contradiction the behavioral eval would only find by re-running the whole
+// family; this script finds it mechanically. Shape errors block; fixture
+// hygiene (unknown neighbour names, one-sided references, missing or short
+// fixtures) warns.
+//
+// Exit codes: 0 pass · 1 warnings under --strict · 2 blocked or usage error.
+// Usage: node trigger-check.mjs [--dir <repo-root>] [--strict] [--json]
+// Self-contained on purpose apart from the repo's skill-discovery lib: skillify
+// is repo-only, so the relative import to packages/cli is always present.
+import { readFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { discoverSkills } from '../../../../packages/cli/scripts/lib/skills.mjs';
+
+const MIN_ENTRIES = 8;
+const FIXTURE = join('tests', 'fixtures', 'trigger-queries.json');
+
+// Located messages are built by concatenation, not template literals. The skill
+// scanner's bounded shell parser reads a backtick preceded by whitespace or one
+// of ;|&()<>/ as a command substitution and reports static_parse_limit when the
+// first whitespace-delimited token inside it carries a $ expansion — wherever
+// the literal sits (an argument or an assignment; bisected in issue 104, which
+// retired the earlier "assignment position" reading from issue 95). It degrades
+// an analyzer for the whole skill. Concatenation, or a literal that opens with a
+// plain word, scans complete.
+const at = (where, message) => where + ': ' + message;
+const quoted = (text) => '"' + text + '"';
+
+// lowercase → collapse whitespace → trim → strip trailing sentence punctuation.
+export function normalizeQuery(query) {
+  return query.toLowerCase().replace(/\s+/g, ' ').trim().replace(/[.!?,;:]+$/, '');
+}
+
+function isNameArray(value) {
+  return Array.isArray(value) && value.every((name) => typeof name === 'string' && name.length > 0);
+}
+
+// Shape-checks one fixture's entries. Returns the valid entries; every bad
+// entry becomes a block naming the file and index.
+function readEntries(file, data, blocks) {
+  const entries = [];
+  data.forEach((entry, index) => {
+    const where = file + '[' + index + ']';
+    if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+      blocks.push(at(where, 'entry must be an object'));
+      return;
+    }
+    if (typeof entry.query !== 'string' || entry.query.trim().length === 0) {
+      blocks.push(at(where, 'query must be a non-empty string'));
+      return;
+    }
+    if (typeof entry.should_trigger !== 'boolean') {
+      blocks.push(at(where, 'should_trigger must be true or false'));
+      return;
+    }
+    if ('ambiguous_with' in entry && !isNameArray(entry.ambiguous_with)) {
+      blocks.push(at(where, 'ambiguous_with must be an array of skill-name strings'));
+      return;
+    }
+    entries.push({
+      where,
+      query: entry.query.trim(),
+      norm: normalizeQuery(entry.query),
+      positive: entry.should_trigger,
+      names: entry.ambiguous_with ?? [],
+    });
+  });
+  return entries;
+}
+
+// fixtures: Map<skillName, { file, data?, error? } | null>. A key is a skill
+// authored here; null means the skill ships no fixture file.
+export function checkTriggers(fixtures) {
+  const blocks = [];
+  const warns = [];
+  const valid = new Map();
+
+  for (const [skill, input] of fixtures) {
+    if (input === null) {
+      warns.push(at(skill, 'no tests/fixtures/trigger-queries.json — every skill ships one (skillify item 2)'));
+      continue;
+    }
+    if (input.error) {
+      blocks.push(at(input.file, input.error));
+      continue;
+    }
+    if (!Array.isArray(input.data)) {
+      blocks.push(at(input.file, 'fixture must be a JSON array of entries'));
+      continue;
+    }
+    const entries = readEntries(input.file, input.data, blocks);
+    if (entries.length < MIN_ENTRIES) warns.push(at(skill, entries.length + ' fixture entries, fewer than ' + MIN_ENTRIES));
+    valid.set(skill, entries);
+  }
+
+  // Per-entry hygiene: neighbour names must be authored here, and a negative
+  // that hands a query to a neighbour needs that neighbour to hold the query.
+  for (const [, entries] of valid) {
+    for (const entry of entries) {
+      for (const name of entry.names) {
+        if (!fixtures.has(name)) {
+          warns.push(at(entry.where, 'ambiguous_with names ' + quoted(name) + ', which is no skill authored here — a typo is invisible to this guard, so confirm the name by hand'));
+          continue;
+        }
+        if (entry.positive) continue;
+        const theirs = valid.get(name);
+        if (theirs && !theirs.some((other) => other.norm === entry.norm)) {
+          warns.push(at(entry.where, 'should_trigger:false hands ' + quoted(entry.query) + ' to ' + name + ', whose fixture has no entry for it — add it there so the family-level eval walks both sides'));
+        }
+      }
+    }
+  }
+
+  // Collisions: index positives by normalised query, then compare each pair of
+  // claiming skills. A skill's claim on a query carries the union of the
+  // neighbour names its positive entries for that query list.
+  const claims = new Map();
+  for (const [skill, entries] of valid) {
+    for (const entry of entries) {
+      if (!entry.positive) continue;
+      const bySkill = claims.get(entry.norm) ?? new Map();
+      const names = bySkill.get(skill) ?? new Set();
+      for (const name of entry.names) names.add(name);
+      bySkill.set(skill, names);
+      claims.set(entry.norm, bySkill);
+    }
+  }
+  for (const [norm, bySkill] of claims) {
+    const skills = [...bySkill.keys()].sort();
+    for (let i = 0; i < skills.length; i += 1) {
+      for (let j = i + 1; j < skills.length; j += 1) {
+        const [x, y] = [skills[i], skills[j]];
+        const xNamesY = bySkill.get(x).has(y);
+        const yNamesX = bySkill.get(y).has(x);
+        if (xNamesY && yNamesX) continue;
+        if (!xNamesY && !yNamesX) {
+          blocks.push(quoted(norm) + ` is should_trigger:true in ${x} and ${y} without a mutual ambiguous_with — merge the trigger or have each fixture name the other`);
+          continue;
+        }
+        const [namer, silent] = xNamesY ? [x, y] : [y, x];
+        warns.push(quoted(norm) + ` is should_trigger:true in ${x} and ${y}; ${namer} names ${silent} in ambiguous_with but ${silent} does not name ${namer} — add the reciprocal entry`);
+      }
+    }
+  }
+
+  blocks.sort();
+  warns.sort();
+  return { blocks, warns };
+}
+
+// One key per discovered skill. ENOENT → null (no fixture); any other read
+// error or a JSON.parse failure → { file, error }; a discovery error throws.
+export async function loadFixtures(repoRoot) {
+  const skills = discoverSkills(join(repoRoot, 'skills'));
+  const fixtures = new Map();
+  for (const [name, skill] of skills) {
+    const path = join(skill.path, FIXTURE);
+    const file = relative(repoRoot, path).split(sep).join('/');
+    let text;
+    try {
+      text = await readFile(path, 'utf8');
+    } catch (error) {
+      fixtures.set(name, error.code === 'ENOENT' ? null : { file, error: error.message });
+      continue;
+    }
+    try {
+      fixtures.set(name, { file, data: JSON.parse(text) });
+    } catch (error) {
+      fixtures.set(name, { file, error: error.message });
+    }
+  }
+  return fixtures;
+}
+
+const invokedDirectly = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  const argv = process.argv.slice(2);
+  const usage = 'usage: trigger-check.mjs [--dir <repo-root>] [--strict] [--json]';
+  let json = false;
+  let strict = false;
+  let dir = resolve(dirname(fileURLToPath(import.meta.url)), '../../../..');
+  let outcome = null;
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--json') json = true;
+    else if (argv[i] === '--strict') strict = true;
+    else if (argv[i] === '--dir' && argv[i + 1] && !argv[i + 1].startsWith('--')) dir = resolve(argv[(i += 1)]);
+    else outcome = { blocks: [usage], warns: [] };
+  }
+  if (!outcome) {
+    try {
+      outcome = checkTriggers(await loadFixtures(dir));
+    } catch (error) {
+      outcome = { blocks: [`cannot discover skills under ${dir}: ${error.message}`], warns: [] };
+    }
+  }
+  const ok = outcome.blocks.length === 0;
+  if (json) {
+    console.log(JSON.stringify({ guard: 'trigger-check', ok, ...outcome }, null, 2));
+  } else {
+    console.log(`trigger-check: ${ok ? (outcome.warns.length ? 'pass with warnings' : 'pass') : 'BLOCKED'}`);
+    for (const b of outcome.blocks) console.log(`  block: ${b}`);
+    for (const w of outcome.warns) console.log(`  warn: ${w}`);
+  }
+  process.exit(ok ? (outcome.warns.length && strict ? 1 : 0) : 2);
+}

package/skill/vegafactory-setup/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: vegafactory-setup
+description: Bootstrap and maintain the org control room — the org, group, people, repos, boards, rules, onboarding, and template files whose defaults every repo's dev profile layers on. Use when asked to "set up the control room", "bootstrap the org for the factory", "register this repo in the control room", "onboard a teammate", "add someone to the org", or "what are the org defaults here", and when a repo's control-room knob names a control room that does not exist yet. Not for a single repo's profile, labels, or knobs (dev-setup), not for architecture advice (dev-architect), not for writing or approving issues (dev-intake), and not for refreshing the local control-room clone (the `vegafactory sync` command).
+---
+
+# vegafactory-setup
+
+Act: give the org one control room, so every repo inherits the answers it would otherwise be asked for.
+
+The control room is `<org>/vegafactory-control-room` — the org profile, the department groups, the people, the repo and board registries, the org-wide rules, the onboarding checklists, and the templates. `dev-setup` reads it before its interview and states an inherited knob instead of asking for it. The layout, the precedence rule, the read path, and what each file may carry live in [control-room](references/control-room.md); this file is the procedure.
+
+Nearest neighbor: `dev-setup` owns one repo's profile — its knobs, labels, runbooks, and AGENTS.md section. This skill owns the defaults that profile layers on. When the question is "what should this repo do", that is dev-setup; when it is "what should every repo do", it is this one.
+
+## Bootstrap — the org questionnaire, then the files, then a stop
+
+1. **Ask the questionnaire.** Only what `org.md` holds and nothing a department owns: the org name, the goals in one paragraph, and what applies to everyone — the language, the date format (DD-MM-YYYY across the workflow), the "nothing ships without the operator's explicit instruction" stance, and the three statistics lines `stats:`, `stats-people:`, `stats-override:`. A knob a department decides — review, gates, merge, the harness policy — is never asked here, because two departments reading one org answer would each need the other's to be wrong.
+2. **Render every template** in `assets/control-room/` into a working directory the operator can read before anything is pushed: `org.md`, `people.csv`, `decisions.md`, `groups/dev/{group.md,people.csv,decisions.md}`, `repos.md`, `boards.md`, `rules/`, `onboarding/`, `templates/`. `people.csv` is seeded from `gh api orgs/<org>/members -q '.[].login'` — the logins come from the API, every `role` is asked for, and a role nobody answered stays unrecorded. Rendering is otherwise substitution only: a template is a default, and a default nobody has confirmed is still a default.
+3. **Stop before the repository exists.** Creating the org repository, granting anyone access, and recording anyone's role are the operator's own account actions. Name the exact commands, say what each one does, and let the operator run them. The skill positions the operator; it does not reach for the credential.
+
+**Nothing secret goes in any file — names of secrets only.** A control room is readable by everyone the org onboards, so `NPM_TOKEN` is the entry and the value stays in the store that name points at.
+
+## Round — automation identity
+
+The org's automated writes go out as the public GitHub App, not as a person's token. This round records the App by name and stops at every step that needs the operator's own account.
+
+1. **Hand the operator the creation walk** in dev-setup's `references/github-app.md` — the permission table, the "Any account" setting, the webhook left off, and the private-key step — rather than restating it here, so the App's contract has one home and one place to update.
+2. **Detect an existing installation:** `gh api orgs/<org>/installations --jq '.installations[] | select(.app_slug == "vegafactory") | .id'`. Write the returned id onto `org.md`'s `app-install:` line.
+3. **Leave the line as an unconfirmed placeholder when the call answers 403 or returns nothing, and say which happened** — the endpoint answers organization owners only, so a 403 means "not an owner", never "no App". An unconfirmed line is a question the next run asks again.
+4. **Never create the App, never ask for the PEM, never write a secret value into any control-room file.** Generating the private key is a browser download GitHub delivers once, to whoever pressed the button; an automated session's download never reaches the operator. Record the two names, `VEGAFACTORY_APP_ID` and `VEGAFACTORY_APP_PRIVATE_KEY`, and leave the values in GitHub org settings.
+
+## Round — the board
+
+A board mirrors the state labels; it never drives them. This round records the board and hands the operator every command that touches a project.
+
+1. **Offer the board on the operator's yes**, one plain sentence: labels drive the workflow and the board follows, one way — a card dragged on the board is cosmetic until the next label change.
+2. **Run nothing that mutates a project.** Creating a board, replacing its Status field, linking a repo and switching on the built-in automations all need the `project` scope on the operator's own token. Hand them the sequence in [control-room](references/control-room.md)'s `## Boards` section verbatim, starting with `gh auth refresh -s project`.
+3. **Write the `boards.md` row** from `assets/control-room/boards.md.template` — board title, number, the repos mirroring onto it, and a notes cell — once the operator reports the number.
+4. **Set `board: <n>`** in each linked repo's `.vegastack/dev.md`, and leave it at `none` for a repo with no board; the workflow reads that line and does nothing when it says `none`.
+5. **Record a blocked repo rather than working around it:** where the org plan's auto-add cap refuses another board workflow, the row in `boards.md` says so with its date and the request goes back to the operator.
+
+## Seeding `groups/<g>/group.md`
+
+A group file carries one default for every knob a group can decide for a repo's `.vegastack/dev.md` — per-repo facts such as `repo:`, `skill-scan:`, `board:` and `control-room:` stay in the repo — so a repo that answers nothing else still gets a complete profile. Seed it from an existing repo's dev.md: confirmed knob lines transfer verbatim, including `harness-policy:`, because a group file uses the same parser. When no confirmed policy exists, use dev-setup's refresh-tracked harness selection and flag mapping in `references/harness-facts.md`; this skill does not freeze vendor model/version defaults. <!-- mirrored -->
+
+A knob whose value differs between two repos in the group is a question, not an average: ask which one is the group's default, and let the other repo keep its hand edit — the precedence rule already protects it.
+
+## `register <repo>`
+
+1. Confirm which group the repo belongs to.
+2. Run `dev-setup` in the repo. It reads the control room first, so every inherited knob is stated rather than asked, and only what no layer answers reaches the interview.
+3. Append the repo's row to `repos.md` — repo, group, board, owner.
+4. Link the board when `boards.md` names one for the group, and copy the board-mirror workflow and the CODEOWNERS pattern from `templates/` and `rules/`.
+5. Confirm the repo's `control-room:` knob names this control room and this group.
+
+The full checklist ships as `onboarding/new-repo.md`, so the org can edit the procedure without editing this skill.
+
+The org's third onboarding path is a machine rather than a repo or a person: `onboarding/dispatcher-box.md` provisions the always-on box that runs the Actions runner and the dispatcher, under two accounts so a CI job cannot read the dispatcher's tokens.
+
+## `onboard <login>`
+
+Walk `onboarding/new-teammate.md` with the person: `gh auth login` at or above the group's `gh-floor:`, the harnesses the group's `harness-policy:` line names, `vegafactory skills add --group dev --global`, control-room read access, and the Slack subscription through the official GitHub Slack app. Then add their `people.csv` row — `login,name,role,slack,timezone,groups`.
+
+**A person's `role` is descriptive and recorded only on the operator's word**, never inferred from org membership. It grants no people-level read authority. Cross-person visibility comes only from the resolved organization/group administration capability and repository read scope in [control-room](references/control-room.md). A group-level row overrides descriptive membership for the same `login`; it cannot override an organization lock or create administration authority without the exact organization delegation.
+
+## The declined step
+
+Every step here can be declined, and a declined step is recorded, not skipped: write it into `org.md`'s `## Unconfirmed` section as one line, in the same form `dev-setup` writes for a knob it could not confirm. The next run asks again. An unrecorded decline becomes an assumption, and an assumption in a file every repo inherits is the most expensive kind.
+
+A control room that does not exist yet, or that the caller cannot read, is not an error either: say which answers could not be inherited and let `dev-setup` ask them.
+
+## Routing
+
+| Need | Read |
+|---|---|
+| the file tree, precedence, read path, `people.csv` rules | [control-room](references/control-room.md) |
+| comment markers, operator identity, register line format, labels | dev-setup's `references/conventions.md`, installed beside this file |
+| the seed text of any control-room file | `assets/control-room/<file>.template` |

package/skill/vegafactory-setup/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "vegafactory-setup"
+  short_description: "Bootstrap and maintain the org control room every repo inherits from"
+  default_prompt: "Use $vegafactory-setup to set up or update this org's control room."

package/skill/vegafactory-setup/assets/control-room/boards.md.template

@@ -0,0 +1,17 @@
+# Boards
+
+Project boards and the repos that mirror onto them. Labels stay the machine state; a board is a view. Several repos may share one board, and one repo may have its own.
+
+**One way only.** `.github/workflows/factory-board.yml` reads a repo's state label and writes the board's Status field. Nothing reads the board: a card dragged on the board is cosmetic until the next label change overwrites it.
+
+Status options, in this order: needs-operator · needs-plan · ready · working · for-operator · Done — the five state labels plus Done, which the built-in automations set.
+
+Built-in automations, switched on once per board in its Workflows UI (no CLI covers them): auto-add `is:issue is:open`, item closed → Done, PR merged → Done, auto-archive after 14 days.
+
+The commands that create, field-configure and link a board are in `vegafactory-setup`'s `references/control-room.md`, and the operator runs them — they need the `project` scope on a human token.
+
+| board | number | repos | notes |
+|---|---|---|---|
+| {{board-title}} | {{number}} | {{owner/repo}} | {{blank, or what this board is for}} |
+
+A repo the org plan's auto-add cap blocks (Team plans allow five auto-add workflows per board) is recorded here with its date and handed back to the operator, never worked around.

package/skill/vegafactory-setup/assets/control-room/decisions.md.template

@@ -0,0 +1,5 @@
+# Decision register — {{scope}}
+
+Append-only, one dated line per directional decision, in the register line format dev-setup's `references/conventions.md` defines. Registers concatenate across org, group, and repo — a line here never overrides one anywhere else.
+
+- DD-MM-YYYY (github-username) — the decision