@moreih29/nexus-core 0.4.0 → 0.6.0

package/scripts/import-from-claude-nexus.ts

@@ -0,0 +1,403 @@
+#!/usr/bin/env bun
+
+import path from 'node:path';
+import { readFile, writeFile, mkdir, readdir, rm, rename, stat } from 'node:fs/promises';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { execSync } from 'node:child_process';
+import { glob } from 'tinyglobby';
+import { parseFrontmatter } from './lib/frontmatter.ts';
+
+// Neutral layer allowed fields (bridge §2.1)
+const AGENT_ALLOW_FIELDS = new Set([
+  'id', 'name', 'alias_ko', 'description', 'task',
+  'category', 'capabilities', 'resume_tier', 'model_tier',
+]);
+const SKILL_ALLOW_FIELDS = new Set([
+  'id', 'name', 'description', 'triggers', 'alias_ko', 'manual_only',
+]);
+
+// Explicitly known drop list (warn + drop)
+const AGENT_DROP_FIELDS = new Set(['maxTurns', 'tags', 'disallowedTools', 'model']);
+// 'disable-model-invocation' is NOT in this set — it is mapped to manual_only below.
+const SKILL_DROP_FIELDS = new Set(['trigger_display', 'purpose']);
+
+// model name → model_tier abstraction
+const MODEL_TIER_MAP: Record<string, 'high' | 'standard'> = {
+  opus: 'high',
+  sonnet: 'standard',
+  haiku: 'standard',
+};
+
+interface ImportOptions {
+  source: string;
+  apply: boolean;
+  agentsOnly: boolean;
+  skillsOnly: boolean;
+}
+
+function parseCli(): ImportOptions {
+  const args = process.argv.slice(2);
+  let source = process.env['NEXUS_CLAUDE_NEXUS_PATH'] ?? path.resolve('..', 'claude-nexus');
+  let apply = false;
+  let agentsOnly = false;
+  let skillsOnly = false;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--source' && args[i + 1]) { source = path.resolve(args[++i]!); }
+    else if (args[i] === '--apply') { apply = true; }
+    else if (args[i] === '--agents-only') { agentsOnly = true; }
+    else if (args[i] === '--skills-only') { skillsOnly = true; }
+  }
+  if (agentsOnly && skillsOnly) {
+    throw new Error('--agents-only and --skills-only are mutually exclusive');
+  }
+  return { source, apply, agentsOnly, skillsOnly };
+}
+
+async function verifySourceIsClaudeNexus(source: string): Promise<void> {
+  const pkgPath = path.join(source, 'package.json');
+  try {
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf8')) as { name?: string };
+    if (pkg.name !== 'claude-nexus') {
+      throw new Error(`source package.json.name='${pkg.name}', expected 'claude-nexus'`);
+    }
+  } catch (err) {
+    throw new Error(`Failed to verify source at ${source}: ${(err as Error).message}`);
+  }
+}
+
+function gitWorkingTreeClean(root: string, scopes: string[]): boolean {
+  try {
+    const out = execSync(`git status --porcelain ${scopes.join(' ')}`, { cwd: root, encoding: 'utf8' });
+    return out.trim().length === 0;
+  } catch {
+    return true; // directory not yet created, treat as clean
+  }
+}
+
+// ---- Body transformation ----
+// <role>...</role> → ## Role ... (top-level section marker only)
+// <constraints>...</constraints> → ## Constraints ...
+// <guidelines>...</guidelines> → ## Guidelines ...
+// inline <example>, <thinking> etc. sub-XML blocks are preserved
+function transformBody(rawBody: string): string {
+  const sections: Array<[RegExp, string]> = [
+    [/<role>\s*\n?/g, '## Role\n\n'],
+    [/<\/role>\s*\n?/g, '\n\n'],
+    [/<constraints>\s*\n?/g, '## Constraints\n\n'],
+    [/<\/constraints>\s*\n?/g, '\n\n'],
+    [/<guidelines>\s*\n?/g, '## Guidelines\n\n'],
+    [/<\/guidelines>\s*\n?/g, '\n\n'],
+  ];
+  let result = rawBody;
+  for (const [re, replacement] of sections) {
+    result = result.replace(re, replacement);
+  }
+  // Trim excessive blank lines
+  return result.replace(/\n{3,}/g, '\n\n').trim() + '\n';
+}
+
+// ---- Capability reverse mapping ----
+// disallowedTools → capabilities reverse mapping
+interface CapabilityEntry {
+  id: string;
+  harness_mapping: {
+    claude_code: string[];
+    opencode: string[];
+  };
+}
+
+interface CapabilitiesFile {
+  capabilities: CapabilityEntry[];
+}
+
+async function loadCapabilityMap(root: string): Promise<Map<string, string>> {
+  const raw = await readFile(path.join(root, 'vocabulary/capabilities.yml'), 'utf8');
+  const caps = parseYaml(raw) as CapabilitiesFile;
+  const map = new Map<string, string>();
+  for (const cap of caps.capabilities) {
+    for (const tool of cap.harness_mapping.claude_code) {
+      map.set(tool, cap.id);
+    }
+    for (const tool of cap.harness_mapping.opencode) {
+      map.set(tool, cap.id);
+    }
+  }
+  return map;
+}
+
+function reverseMapTools(disallowedTools: string[], capMap: Map<string, string>): string[] {
+  const capabilitySet = new Set<string>();
+  for (const tool of disallowedTools) {
+    const cap = capMap.get(tool);
+    if (cap) capabilitySet.add(cap);
+  }
+  return Array.from(capabilitySet).sort();
+}
+
+// ---- Agent transformation ----
+interface TransformedAgent {
+  id: string;
+  meta: Record<string, unknown>;
+  body: string;
+}
+
+async function transformAgent(
+  sourcePath: string,
+  capMap: Map<string, string>,
+  warnings: string[]
+): Promise<TransformedAgent | null> {
+  const source = await readFile(sourcePath, 'utf8');
+  const { data, content } = parseFrontmatter(source);
+  const fileName = path.basename(sourcePath, '.md');
+
+  const meta: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (AGENT_ALLOW_FIELDS.has(key)) {
+      if (key === 'capabilities') continue; // will be computed from disallowedTools
+      meta[key] = value;
+    } else if (AGENT_DROP_FIELDS.has(key)) {
+      warnings.push(`  ${fileName}: dropping known field '${key}'`);
+    } else {
+      throw new Error(`${fileName}: unknown field '${key}' — add to allow list or drop list`);
+    }
+  }
+
+  // model → model_tier
+  if (typeof data['model'] === 'string') {
+    const tier = MODEL_TIER_MAP[data['model']];
+    if (!tier) throw new Error(`${fileName}: unknown model '${data['model']}'`);
+    meta['model_tier'] = tier;
+  }
+
+  // disallowedTools → capabilities
+  const disallowed = Array.isArray(data['disallowedTools']) ? data['disallowedTools'] : [];
+  meta['capabilities'] = reverseMapTools(disallowed as string[], capMap);
+
+  // Ensure id present (use filename if not in frontmatter)
+  if (!meta['id']) meta['id'] = fileName;
+
+  // name default to id
+  if (!meta['name']) meta['name'] = meta['id'];
+
+  const body = transformBody(content);
+
+  return { id: meta['id'] as string, meta, body };
+}
+
+// ---- Skill transformation ----
+interface TransformedSkill {
+  id: string;
+  meta: Record<string, unknown>;
+  body: string;
+}
+
+async function transformSkill(
+  sourceDir: string,
+  warnings: string[]
+): Promise<TransformedSkill | null> {
+  const skillFile = path.join(sourceDir, 'SKILL.md');
+  const source = await readFile(skillFile, 'utf8');
+  const { data, content } = parseFrontmatter(source);
+  const skillId = path.basename(sourceDir);
+
+  const meta: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (SKILL_ALLOW_FIELDS.has(key)) {
+      meta[key] = value;
+    } else if (SKILL_DROP_FIELDS.has(key)) {
+      warnings.push(`  ${skillId}: dropping known field '${key}'`);
+    } else if (key === 'disable-model-invocation') {
+      // Map to manual_only
+      meta['manual_only'] = Boolean(value);
+      warnings.push(`  ${skillId}: mapping disable-model-invocation → manual_only`);
+    } else {
+      throw new Error(`${skillId}: unknown field '${key}' — add to allow list or drop list`);
+    }
+  }
+
+  // Normalize triggers: bracket strings → tag ids; slash commands → drop + manual_only
+  if (Array.isArray(meta['triggers'])) {
+    const rawTriggers = meta['triggers'] as string[];
+    // Bracket triggers (e.g., [plan], [plan:auto]): strip brackets, split on ':' for parent id
+    const bracketTriggers = rawTriggers
+      .filter((t) => t.startsWith('[') && t.endsWith(']'))
+      .map((t) => t.slice(1, -1).split(':')[0]!)
+      .filter((t, i, arr) => arr.indexOf(t) === i); // dedupe
+    // Slash command triggers (e.g., /claude-nexus:nx-init): harness-specific, drop them
+    const slashTriggers = rawTriggers.filter((t) => t.startsWith('/'));
+    if (slashTriggers.length > 0) {
+      warnings.push(`  ${skillId}: slash command triggers detected (${slashTriggers.join(', ')}) → dropping + setting manual_only: true`);
+      meta['manual_only'] = true;
+    }
+    if (bracketTriggers.length > 0) {
+      meta['triggers'] = bracketTriggers;
+    } else {
+      delete meta['triggers'];
+    }
+  }
+
+  if (!meta['id']) meta['id'] = skillId;
+  if (!meta['name']) meta['name'] = meta['id'];
+
+  const body = transformBody(content);
+
+  return { id: meta['id'] as string, meta, body };
+}
+
+// ---- Staging + atomic rename ----
+async function writeToStaging(
+  root: string,
+  kind: 'agents' | 'skills',
+  items: Array<{ id: string; meta: Record<string, unknown>; body: string }>
+): Promise<void> {
+  const stagingDir = path.join(root, `${kind}.staging`);
+  await rm(stagingDir, { recursive: true, force: true });
+  await mkdir(stagingDir, { recursive: true });
+  for (const item of items) {
+    const dir = path.join(stagingDir, item.id);
+    await mkdir(dir, { recursive: true });
+    await writeFile(path.join(dir, 'meta.yml'), stringifyYaml(item.meta));
+    await writeFile(path.join(dir, 'body.md'), item.body);
+  }
+}
+
+async function atomicSwap(root: string, kind: 'agents' | 'skills'): Promise<void> {
+  const live = path.join(root, kind);
+  const staging = path.join(root, `${kind}.staging`);
+  const backup = path.join(root, `${kind}.backup`);
+  // If live exists, move it to backup
+  try {
+    await stat(live);
+    await rm(backup, { recursive: true, force: true });
+    await rename(live, backup);
+  } catch {
+    // live doesn't exist — first bootstrap
+  }
+  await rename(staging, live);
+}
+
+async function cleanupBackup(root: string, kind: 'agents' | 'skills'): Promise<void> {
+  const backup = path.join(root, `${kind}.backup`);
+  await rm(backup, { recursive: true, force: true });
+}
+
+async function restoreBackup(root: string, kind: 'agents' | 'skills'): Promise<void> {
+  const live = path.join(root, kind);
+  const backup = path.join(root, `${kind}.backup`);
+  try {
+    await rm(live, { recursive: true, force: true });
+    await rename(backup, live);
+  } catch {
+    /* nothing to restore */
+  }
+}
+
+// ---- Main ----
+async function main(): Promise<void> {
+  const opts = parseCli();
+  const root = process.cwd();
+
+  console.log('# nexus-core import-from-claude-nexus');
+  console.log(`Source: ${opts.source}`);
+  console.log(`Target: ${root}`);
+  console.log(`Mode: ${opts.apply ? 'APPLY' : 'DRY-RUN'}`);
+  console.log('');
+
+  // Verify source
+  await verifySourceIsClaudeNexus(opts.source);
+
+  // Git working tree dirty check
+  if (opts.apply) {
+    const scopes = ['agents/', 'skills/', 'manifest.json'];
+    if (!gitWorkingTreeClean(root, scopes)) {
+      throw new Error('Working tree has uncommitted changes in agents/, skills/, or manifest.json. Commit or stash first.');
+    }
+  }
+
+  // Load capability map
+  const capMap = await loadCapabilityMap(root);
+
+  // Collect source files
+  const agentFiles = opts.skillsOnly
+    ? []
+    : await glob(['agents/*.md'], { cwd: opts.source, absolute: true });
+  const skillDirs = opts.agentsOnly
+    ? []
+    : await glob(['skills/*'], { cwd: opts.source, absolute: true, onlyDirectories: true });
+
+  const warnings: string[] = [];
+  const transformedAgents: TransformedAgent[] = [];
+  const transformedSkills: TransformedSkill[] = [];
+
+  // Transform agents
+  for (const f of agentFiles) {
+    const agent = await transformAgent(f, capMap, warnings);
+    if (agent) transformedAgents.push(agent);
+  }
+
+  // Transform skills
+  for (const d of skillDirs) {
+    const skill = await transformSkill(d, warnings);
+    if (skill) transformedSkills.push(skill);
+  }
+
+  console.log('# Transformation summary');
+  console.log(`Agents: ${transformedAgents.length}`);
+  console.log(`Skills: ${transformedSkills.length}`);
+  if (warnings.length > 0) {
+    console.log('# Warnings');
+    for (const w of warnings) console.log(w);
+  }
+  console.log('');
+
+  if (!opts.apply) {
+    console.log('# Files that would be written (dry-run):');
+    for (const a of transformedAgents) {
+      console.log(`  agents/${a.id}/meta.yml`);
+      console.log(`  agents/${a.id}/body.md`);
+    }
+    for (const s of transformedSkills) {
+      console.log(`  skills/${s.id}/meta.yml`);
+      console.log(`  skills/${s.id}/body.md`);
+    }
+    console.log('');
+    console.log('Run with --apply to write.');
+    return;
+  }
+
+  // Apply — all-or-nothing transaction via staging
+  try {
+    if (!opts.skillsOnly) {
+      await writeToStaging(root, 'agents', transformedAgents);
+      await atomicSwap(root, 'agents');
+    }
+    if (!opts.agentsOnly) {
+      await writeToStaging(root, 'skills', transformedSkills);
+      await atomicSwap(root, 'skills');
+    }
+  } catch (err) {
+    console.error('Import failed during write phase. Attempting restore...');
+    if (!opts.skillsOnly) await restoreBackup(root, 'agents');
+    if (!opts.agentsOnly) await restoreBackup(root, 'skills');
+    throw err;
+  }
+
+  // Cleanup backup on success
+  if (!opts.skillsOnly) await cleanupBackup(root, 'agents');
+  if (!opts.agentsOnly) await cleanupBackup(root, 'skills');
+
+  console.log('');
+  console.log('Import complete. Running validate...');
+  // Auto-validate after apply — run validate via spawnSync
+  const { spawnSync } = await import('node:child_process');
+  const res = spawnSync('bun', ['run', 'validate'], { cwd: root, stdio: 'inherit' });
+  if (res.status !== 0) {
+    throw new Error('Validation failed after import. Check output above.');
+  }
+  console.log('Import + validation complete.');
+}
+
+main().catch((err) => {
+  console.error('Error:', (err as Error).message);
+  process.exit(1);
+});

package/scripts/lib/frontmatter.ts

@@ -0,0 +1,71 @@
+import { parse as parseYaml } from 'yaml';
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
+
+export interface ParsedFrontmatter {
+  /** parsed YAML object */
+  data: Record<string, unknown>;
+  /** body content (after closing ---) */
+  content: string;
+  /** 1-based line number where frontmatter YAML starts (after opening ---) */
+  frontmatterStartLine: number;
+  /** 1-based line number where body content starts (after closing ---) */
+  contentStartLine: number;
+}
+
+/**
+ * Parses a markdown file with optional YAML frontmatter.
+ *
+ * Format:
+ *   ---
+ *   {frontmatter YAML}
+ *   ---
+ *   {body content}
+ *
+ * If no frontmatter is present, returns {data: {}, content: source, frontmatterStartLine: 0, contentStartLine: 1}.
+ *
+ * Line numbers are 1-based to match editor conventions.
+ */
+export function parseFrontmatter(source: string): ParsedFrontmatter {
+  const match = source.match(FRONTMATTER_RE);
+  if (!match) {
+    return {
+      data: {},
+      content: source,
+      frontmatterStartLine: 0,
+      contentStartLine: 1,
+    };
+  }
+
+  const frontmatterText = match[1];
+  const body = match[2];
+  const parsed = parseYaml(frontmatterText);
+
+  // Opening '---' is line 1, frontmatter YAML starts at line 2
+  const frontmatterStartLine = 2;
+  // Count lines in frontmatter text + 2 (opening --- and closing ---)
+  const frontmatterLineCount = frontmatterText.split('\n').length;
+  const contentStartLine = frontmatterStartLine + frontmatterLineCount + 1; // +1 for closing ---
+
+  return {
+    data: (parsed ?? {}) as Record<string, unknown>,
+    content: body,
+    frontmatterStartLine,
+    contentStartLine,
+  };
+}
+
+/**
+ * Reverse: translates a line number within the frontmatter YAML (1-based, as reported
+ * by a YAML parser operating on the frontmatter text alone) back to the line in the
+ * original source file.
+ */
+export function frontmatterLineToSourceLine(
+  parsed: ParsedFrontmatter,
+  frontmatterLine: number
+): number {
+  if (parsed.frontmatterStartLine === 0) {
+    throw new Error('Source has no frontmatter');
+  }
+  return parsed.frontmatterStartLine + frontmatterLine - 1;
+}

package/scripts/lib/lint.ts

@@ -0,0 +1,216 @@
+import { glob } from 'tinyglobby';
+import { readFile } from 'node:fs/promises';
+import { parse as parseYaml } from 'yaml';
+import path from 'node:path';
+
+/**
+ * Common ValidationResult type. Imported from ./validate.ts for consistency,
+ * but declared here as well for isolation.
+ */
+export interface ValidationResult {
+  file: string;
+  gate: string;
+  severity: 'error' | 'warning';
+  line?: number;
+  message: string;
+}
+
+/** Paths excluded from all lint checks. */
+const LINT_EXCLUDE: string[] = [
+  'scripts/**',
+  'node_modules/**',
+  '.git/**',
+  'dist/**',
+  '.nexus/**',
+  'schema/**',
+  // capabilities.yml prose_guidance naturally uses English words (Read, edit, write)
+  // that match tool-name regexes. After v0.2.0 harness-agnostic redesign, this file
+  // contains zero harness tool names — only semantic descriptions. Excluding is safe.
+  'vocabulary/capabilities.yml',
+];
+
+/**
+ * Patterns to scan — only prompt-injection sources and canonical vocabulary.
+ *
+ * Intentionally excluded: README.md, CONSUMING.md, CHANGELOG.md, MIGRATIONS/*,
+ * schema/README.md — these are human-facing documentation where harness tool
+ * names and model names may legitimately appear in prose explanations.
+ */
+const LINT_INCLUDE: string[] = [
+  'agents/**/meta.yml',
+  'agents/**/body.md',
+  'skills/**/meta.yml',
+  'skills/**/body.md',
+  'vocabulary/*.yml',
+];
+
+// G6: harness-specific tool names
+// Distinctive tools — unambiguous, safe to scan in ALL files including body.md prose
+const CLAUDE_CODE_TOOLS_DISTINCTIVE = /\b(NotebookEdit|BashOutput|KillShell|Glob|Grep|WebFetch|WebSearch|TodoWrite|SendMessage|TeamCreate|AskUserQuestion|mcp__plugin_[a-z0-9_]+)\b/g;
+// Ambiguous tools — also common English words (Read, Write, Edit, Bash, Task, Monitor)
+// Only scanned in meta.yml and vocabulary where they are clearly tool references, not prose.
+const CLAUDE_CODE_TOOLS_AMBIGUOUS = /\b(Read|Write|Edit|Bash|Task|Monitor)\b/g;
+const OPENCODE_TOOLS = /\b(edit|write|patch|multiedit|bash)\b/g;
+
+// G7: concrete model names
+const CONCRETE_MODELS = /\b(opus|sonnet|haiku|gpt-[0-9][a-z0-9.-]*|claude-[0-9][a-z0-9.-]*)\b/gi;
+
+// G8: non-TS/JS file allowed extensions
+const PROMPT_ONLY_BAD_EXT = /\.(ts|tsx|js|jsx|cjs|mjs)$/;
+
+async function* iterFiles(root: string): AsyncGenerator<string> {
+  const files = await glob(LINT_INCLUDE, {
+    cwd: root,
+    ignore: LINT_EXCLUDE,
+    absolute: true,
+    onlyFiles: true,
+  });
+  for (const f of files) yield f;
+}
+
+function lineOfMatch(source: string, index: number): number {
+  return source.slice(0, index).split('\n').length;
+}
+
+function scanRegex(
+  source: string,
+  regex: RegExp,
+  file: string,
+  gate: string,
+  makeMessage: (match: string) => string
+): ValidationResult[] {
+  const results: ValidationResult[] = [];
+  regex.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  // eslint-disable-next-line no-cond-assign
+  while ((m = regex.exec(source)) !== null) {
+    results.push({
+      file,
+      gate,
+      severity: 'error',
+      line: lineOfMatch(source, m.index),
+      message: makeMessage(m[0]),
+    });
+    if (m.index === regex.lastIndex) regex.lastIndex++;
+  }
+  return results;
+}
+
+/** G6: harness-specific tool names forbidden in body/meta/vocabulary.
+ *
+ * CLAUDE_CODE_TOOLS (capitalized, distinctive) — scanned in ALL lint-included files.
+ * OPENCODE_TOOLS (lowercase, indistinguishable from English words in prose) — scanned
+ * ONLY in meta.yml and vocabulary/*.yml, NOT in body.md or prose_guidance fields.
+ * Rationale: "edit", "write", "bash" are common English words that legitimately appear
+ * in descriptive body prose. Scanning body.md for these produces mass false positives.
+ */
+export async function checkHarnessSpecific(root: string): Promise<ValidationResult[]> {
+  const results: ValidationResult[] = [];
+  for await (const file of iterFiles(root)) {
+    const source = await readFile(file, 'utf8');
+    const rel = path.relative(root, file);
+    // Distinctive Claude Code tools (unambiguous) — all files
+    results.push(
+      ...scanRegex(source, CLAUDE_CODE_TOOLS_DISTINCTIVE, rel, 'G6-harness-lint',
+        (m) => `Harness-specific tool name forbidden: '${m}'. Use abstract capability or remove.`)
+    );
+    // Ambiguous tools (Read/Write/Edit/Bash/Task/Monitor + OpenCode lowercase) — meta.yml and vocabulary only
+    if (rel.endsWith('meta.yml') || rel.startsWith('vocabulary/')) {
+      results.push(
+        ...scanRegex(source, CLAUDE_CODE_TOOLS_AMBIGUOUS, rel, 'G6-harness-lint',
+          (m) => `Harness-specific tool name forbidden: '${m}'. Use abstract capability or remove.`)
+      );
+      results.push(
+        ...scanRegex(source, OPENCODE_TOOLS, rel, 'G6-harness-lint',
+          (m) => `OpenCode tool name forbidden: '${m}'. Use abstract capability or remove.`)
+      );
+    }
+  }
+  return results;
+}
+
+/** G7: concrete model names forbidden; use model_tier abstraction. */
+export async function checkConcreteModel(root: string): Promise<ValidationResult[]> {
+  const results: ValidationResult[] = [];
+  for await (const file of iterFiles(root)) {
+    const source = await readFile(file, 'utf8');
+    const rel = path.relative(root, file);
+    results.push(
+      ...scanRegex(source, CONCRETE_MODELS, rel, 'G7-model-lint',
+        (m) => `Concrete model name forbidden: '${m}'. Use 'model_tier: high | standard'.`)
+    );
+  }
+  return results;
+}
+
+/**
+ * G11: tag trigger consistency — each tag's trigger must equal "[" + id.replace(/-/g, ":") + "]".
+ */
+export async function checkTagTriggerConsistency(root: string): Promise<ValidationResult[]> {
+  const tagsPath = path.join(root, 'vocabulary', 'tags.yml');
+  const rel = path.join('vocabulary', 'tags.yml');
+  let source: string;
+  try {
+    source = await readFile(tagsPath, 'utf8');
+  } catch (err) {
+    return [{
+      file: rel,
+      gate: 'G11-tag-trigger',
+      severity: 'error',
+      message: `Cannot read tags.yml: ${(err as Error).message}`,
+    }];
+  }
+
+  let data: unknown;
+  try {
+    data = parseYaml(source);
+  } catch (err) {
+    return [{
+      file: rel,
+      gate: 'G11-tag-trigger',
+      severity: 'error',
+      message: `YAML parse error in tags.yml: ${(err as Error).message}`,
+    }];
+  }
+
+  const tags = (data as { tags?: Array<{ id: string; trigger: string }> })?.tags ?? [];
+  const results: ValidationResult[] = [];
+  for (const tag of tags) {
+    const expected = '[' + tag.id.replace(/-/g, ':') + ']';
+    if (tag.trigger !== expected) {
+      results.push({
+        file: rel,
+        gate: 'G11-tag-trigger',
+        severity: 'error',
+        message: `Tag '${tag.id}': trigger mismatch — expected '${expected}', got '${tag.trigger}'`,
+      });
+    }
+  }
+  return results;
+}
+
+/**
+ * G8: prompt-only enforcement — no .ts/.js/.cjs/.mjs outside scripts/.
+ * Published artifact must not contain runtime code.
+ */
+export async function checkPromptOnly(root: string): Promise<ValidationResult[]> {
+  const results: ValidationResult[] = [];
+  const allFiles = await glob(['**/*'], {
+    cwd: root,
+    ignore: ['node_modules/**', '.git/**', 'dist/**', '.nexus/**', 'scripts/**'],
+    absolute: true,
+    onlyFiles: true,
+  });
+  for (const file of allFiles) {
+    if (PROMPT_ONLY_BAD_EXT.test(file)) {
+      const rel = path.relative(root, file);
+      results.push({
+        file: rel,
+        gate: 'G8-prompt-only',
+        severity: 'error',
+        message: `Runtime code file outside scripts/: ${rel}. nexus-core is a prompt-only library.`,
+      });
+    }
+  }
+  return results;
+}