@rune-kit/rune 2.13.0 → 2.15.0

package/compiler/__tests__/context-pack-smell-tests.test.js

@@ -0,0 +1,215 @@
+/**
+ * Context-pack v0.2 smell tests — regex gates that catch rot-prone briefs.
+ *
+ * BLOCK regex must catch:
+ *   - file:line references (login.ts:42)
+ *   - "line N" / "on line N" patterns
+ *   - Path-only narrative bullets outside Files Touched section
+ *
+ * WARN regex must catch:
+ *   - Bare path mentions in narrative (advisory, not blocking)
+ *
+ * Mandatory sections must be enforced:
+ *   - ### Out of scope (always)
+ *   - ### Type Surface (when task >= 300 tokens)
+ */
+
+import assert from 'node:assert';
+import { describe, test } from 'node:test';
+
+// --- Smell-test regex (mirrors durability-rules.md) ---
+
+const FILE_LINE_RE = /\b\S+\.[a-z]{1,4}:\d+\b/;
+const LINE_N_RE = /\b(line |on line )\d+\b/i;
+const NARRATIVE_PATH_RE = /\b(src|lib|app)\/\S+/;
+
+function runSmellTests(packet) {
+  const violations = { block: [], warn: [] };
+
+  if (FILE_LINE_RE.test(packet)) {
+    const m = packet.match(FILE_LINE_RE);
+    violations.block.push({ rule: 'file:line', match: m[0] });
+  }
+
+  if (LINE_N_RE.test(packet)) {
+    const m = packet.match(LINE_N_RE);
+    violations.block.push({ rule: 'line N', match: m[0] });
+  }
+
+  // Narrative path: only WARN if it appears OUTSIDE the Files Touched section.
+  const filesTouchedMatch = packet.match(/### Files Touched[\s\S]*?(?=\n### |\n## |$)/);
+  const filesTouchedBlock = filesTouchedMatch ? filesTouchedMatch[0] : '';
+  // Strip the Files Touched section before scanning
+  const narrative = packet.replace(filesTouchedBlock, '');
+  if (NARRATIVE_PATH_RE.test(narrative)) {
+    const m = narrative.match(NARRATIVE_PATH_RE);
+    violations.warn.push({ rule: 'narrative path', match: m[0] });
+  }
+
+  return violations;
+}
+
+function checkMandatorySections(packet, taskTokenCount = 0) {
+  const issues = [];
+  if (!/### Out of scope/.test(packet)) {
+    issues.push('missing ### Out of scope section');
+  }
+  if (taskTokenCount >= 300 && !/### Type Surface/.test(packet)) {
+    issues.push('missing ### Type Surface section (mandatory for tasks >= 300 tokens)');
+  }
+  return issues;
+}
+
+// --- Tests ---
+
+describe('context-pack smell tests', () => {
+  describe('BLOCK tier — file:line references', () => {
+    test('catches login.ts:42', () => {
+      const packet = '## Context Packet\n\n**Task**: Modify the function at src/auth/login.ts:42';
+      const v = runSmellTests(packet);
+      assert.strictEqual(v.block.length, 1);
+      assert.strictEqual(v.block[0].rule, 'file:line');
+    });
+
+    test('catches handler.py:100', () => {
+      const packet = 'See handler.py:100 for the bug';
+      const v = runSmellTests(packet);
+      assert.strictEqual(v.block.length, 1);
+    });
+
+    test('catches main.go:5', () => {
+      const packet = 'In main.go:5 the import is wrong';
+      const v = runSmellTests(packet);
+      assert.strictEqual(v.block.length, 1);
+    });
+  });
+
+  describe('BLOCK tier — line N references', () => {
+    test('catches "line 42"', () => {
+      const packet = 'The bug is on line 42 of the file';
+      const v = runSmellTests(packet);
+      assert.strictEqual(v.block.length, 1);
+      assert.strictEqual(v.block[0].rule, 'line N');
+    });
+
+    test('catches "on line 100"', () => {
+      const packet = 'See on line 100 below';
+      const v = runSmellTests(packet);
+      assert.strictEqual(v.block.length, 1);
+    });
+
+    test('catches case-insensitive "Line 42"', () => {
+      const packet = 'Look at Line 42';
+      const v = runSmellTests(packet);
+      assert.strictEqual(v.block.length, 1);
+    });
+  });
+
+  describe('WARN tier — narrative paths', () => {
+    test('warns on narrative `src/auth/`', () => {
+      const packet = '## Context Packet\n\nThe work happens in src/auth/handlers';
+      const v = runSmellTests(packet);
+      assert.strictEqual(v.warn.length, 1);
+    });
+
+    test('does NOT warn when path is only in Files Touched section', () => {
+      const packet = `## Context Packet
+
+**Task**: Add device tracking
+
+### Files Touched (locator-only)
+- src/auth/login.ts (LoginInput, AuthService.authenticate) — handler
+
+### Out of scope
+- (none)`;
+      const v = runSmellTests(packet);
+      assert.strictEqual(v.warn.length, 0, 'paths in Files Touched are allowed');
+    });
+  });
+
+  describe('clean packets pass', () => {
+    test('valid v2 packet has zero violations', () => {
+      const packet = `## Context Packet
+
+**Task**: Add device_id to login flow
+**Parent**: cook
+**Scope**: AuthService, LoginInput
+
+### Decisions Made
+- Pass through to session storage
+
+### Constraints
+- MUST: preserve backward-compat
+- MUST NOT: change rate-limit window
+
+### Type Surface (durable)
+- LoginInput { email: string; password: string; device_id?: string }
+- AuthService.authenticate(input: LoginInput): Result<Session, AuthError>
+
+### Files Touched (locator-only)
+- src/auth/login.ts (LoginInput, AuthService.authenticate) — route handler
+
+### Acceptance Criteria
+- [ ] Persists device_id when provided
+- [ ] Returns AuthError when credentials invalid
+
+### Out of scope
+- Audit log writer
+`;
+      const v = runSmellTests(packet);
+      assert.strictEqual(v.block.length, 0, `expected 0 BLOCK, got: ${JSON.stringify(v.block)}`);
+      // narrative section uses "AuthService" — no path mention outside Files Touched
+      assert.strictEqual(v.warn.length, 0, `expected 0 WARN, got: ${JSON.stringify(v.warn)}`);
+    });
+  });
+});
+
+describe('mandatory section gate', () => {
+  test('rejects packet missing Out of scope', () => {
+    const packet = `## Context Packet
+**Task**: x
+### Acceptance Criteria
+- [ ] does y
+`;
+    const issues = checkMandatorySections(packet, 100);
+    assert.ok(issues.some((i) => i.includes('Out of scope')));
+  });
+
+  test('rejects packet missing Type Surface for large tasks', () => {
+    const packet = `## Context Packet
+**Task**: large task
+### Out of scope
+- (none)
+### Acceptance Criteria
+- [ ] does y
+`;
+    const issues = checkMandatorySections(packet, 500);
+    assert.ok(issues.some((i) => i.includes('Type Surface')));
+  });
+
+  test('allows packet without Type Surface for small tasks (<300 tokens)', () => {
+    const packet = `## Context Packet
+**Task**: small task
+### Out of scope
+- (none)
+### Acceptance Criteria
+- [ ] does y
+`;
+    const issues = checkMandatorySections(packet, 200);
+    assert.strictEqual(issues.length, 0, `expected pass for small task, got: ${issues.join('\n')}`);
+  });
+
+  test('passes valid packet with all sections', () => {
+    const packet = `## Context Packet
+**Task**: task
+### Type Surface
+- T { x: string }
+### Out of scope
+- (none)
+### Acceptance Criteria
+- [ ] does y
+`;
+    const issues = checkMandatorySections(packet, 500);
+    assert.strictEqual(issues.length, 0);
+  });
+});

package/compiler/__tests__/context-preview-signal.test.js

@@ -0,0 +1,166 @@
+/**
+ * Context preview signal (v2.15+) — verify the schema and threshold logic
+ * for context-engine's preview-gate mode. Caller emits context.preview before
+ * bundling expensive context, gating dispatch on token budget.
+ *
+ * Validates:
+ *   - Signal name conforms to dot-notation pattern
+ *   - Payload schema (caller, estimated_tokens, file_count, top_5, threshold, action)
+ *   - Threshold action enum: proceed | warn | block
+ *   - Caller-specific threshold table (adversary 50k/100k, team 30k/80k, etc.)
+ *   - Token estimate function: chars × 0.25
+ *   - Decision function: tokens >= block_at → block, >= warn_at → warn, else proceed
+ */
+
+import assert from 'node:assert';
+import { describe, test } from 'node:test';
+
+const SIGNAL_PATTERN = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)+$/;
+
+const VALID_CALLERS = new Set(['adversary', 'team', 'review', 'audit']);
+const VALID_ACTIONS = new Set(['proceed', 'warn', 'block']);
+
+const DEFAULT_THRESHOLDS = {
+  adversary: { warn_at: 50_000, block_at: 100_000 },
+  team: { warn_at: 30_000, block_at: 80_000 },
+  review: { warn_at: 40_000, block_at: 100_000 },
+  audit: { warn_at: 60_000, block_at: 120_000 },
+};
+
+function estimateTokens(chars) {
+  return Math.floor(chars * 0.25);
+}
+
+function decideAction(estimatedTokens, threshold) {
+  if (estimatedTokens >= threshold.block_at) return 'block';
+  if (estimatedTokens >= threshold.warn_at) return 'warn';
+  return 'proceed';
+}
+
+function buildPreviewPayload({ caller, files, promptChars = 200 }) {
+  if (!VALID_CALLERS.has(caller)) throw new Error(`unknown caller: ${caller}`);
+  const threshold = DEFAULT_THRESHOLDS[caller];
+  const totalChars = promptChars + files.reduce((sum, f) => sum + f.chars, 0);
+  const estimated_tokens = estimateTokens(totalChars);
+  const top_5_files_by_size = [...files].sort((a, b) => b.chars - a.chars).slice(0, 5);
+  return {
+    caller,
+    estimated_tokens,
+    file_count: files.length,
+    top_5_files_by_size,
+    threshold,
+    action: decideAction(estimated_tokens, threshold),
+  };
+}
+
+function validatePayload(payload) {
+  const errors = [];
+  if (!VALID_CALLERS.has(payload.caller)) errors.push('invalid_caller');
+  if (typeof payload.estimated_tokens !== 'number' || payload.estimated_tokens < 0) errors.push('invalid_tokens');
+  if (typeof payload.file_count !== 'number' || payload.file_count < 0) errors.push('invalid_file_count');
+  if (!Array.isArray(payload.top_5_files_by_size) || payload.top_5_files_by_size.length > 5)
+    errors.push('invalid_top_5');
+  if (typeof payload.threshold?.warn_at !== 'number' || typeof payload.threshold?.block_at !== 'number')
+    errors.push('invalid_threshold');
+  if (!VALID_ACTIONS.has(payload.action)) errors.push('invalid_action');
+  return { valid: errors.length === 0, errors };
+}
+
+describe('Signal naming compliance', () => {
+  test('context.preview conforms to signal naming pattern', () => {
+    assert.match('context.preview', SIGNAL_PATTERN);
+  });
+});
+
+describe('Payload schema', () => {
+  test('valid payload passes', () => {
+    const payload = buildPreviewPayload({
+      caller: 'adversary',
+      files: [{ path: 'a.ts', chars: 1000 }],
+    });
+    assert.strictEqual(validatePayload(payload).valid, true);
+  });
+
+  test('rejects unknown caller', () => {
+    const payload = buildPreviewPayload({
+      caller: 'adversary',
+      files: [{ path: 'a.ts', chars: 1000 }],
+    });
+    payload.caller = 'unknown_skill';
+    assert.ok(validatePayload(payload).errors.includes('invalid_caller'));
+  });
+
+  test('rejects unknown action', () => {
+    const payload = buildPreviewPayload({
+      caller: 'adversary',
+      files: [{ path: 'a.ts', chars: 1000 }],
+    });
+    payload.action = 'maybe';
+    assert.ok(validatePayload(payload).errors.includes('invalid_action'));
+  });
+
+  test('top_5 capped at 5 entries even with many files', () => {
+    const files = Array.from({ length: 12 }, (_, i) => ({ path: `f${i}.ts`, chars: 100 + i * 10 }));
+    const payload = buildPreviewPayload({ caller: 'team', files });
+    assert.ok(payload.top_5_files_by_size.length <= 5);
+    assert.strictEqual(payload.file_count, 12);
+  });
+});
+
+describe('Token estimation', () => {
+  test('chars × 0.25 = tokens', () => {
+    assert.strictEqual(estimateTokens(4000), 1000);
+    assert.strictEqual(estimateTokens(0), 0);
+    assert.strictEqual(estimateTokens(100_000), 25_000);
+  });
+});
+
+describe('Action decision logic', () => {
+  test('proceed when under warn threshold', () => {
+    const payload = buildPreviewPayload({
+      caller: 'adversary',
+      files: [{ path: 'a.ts', chars: 10_000 }],
+    });
+    assert.strictEqual(payload.action, 'proceed');
+  });
+
+  test('warn when between warn and block', () => {
+    const payload = buildPreviewPayload({
+      caller: 'adversary',
+      files: [{ path: 'a.ts', chars: 280_000 }],
+    });
+    assert.strictEqual(payload.action, 'warn');
+  });
+
+  test('block when at or over block threshold', () => {
+    const payload = buildPreviewPayload({
+      caller: 'adversary',
+      files: [{ path: 'a.ts', chars: 500_000 }],
+    });
+    assert.strictEqual(payload.action, 'block');
+  });
+});
+
+describe('Caller-specific thresholds', () => {
+  test('adversary uses 50k/100k', () => {
+    assert.deepStrictEqual(DEFAULT_THRESHOLDS.adversary, { warn_at: 50_000, block_at: 100_000 });
+  });
+
+  test('team uses lower per-worker thresholds (30k/80k)', () => {
+    assert.deepStrictEqual(DEFAULT_THRESHOLDS.team, { warn_at: 30_000, block_at: 80_000 });
+  });
+
+  test('audit uses higher cross-pack thresholds (60k/120k)', () => {
+    assert.deepStrictEqual(DEFAULT_THRESHOLDS.audit, { warn_at: 60_000, block_at: 120_000 });
+  });
+
+  test('same file scope produces different actions per caller', () => {
+    const files = [{ path: 'big.ts', chars: 200_000 }]; // ~50k tokens
+    const adv = buildPreviewPayload({ caller: 'adversary', files });
+    const team = buildPreviewPayload({ caller: 'team', files });
+    // Adversary: 50k → exactly at warn_at → warn
+    assert.strictEqual(adv.action, 'warn');
+    // Team: 50k > block_at (80k worker cap not hit, but...) actually 50k < 80k → warn
+    assert.strictEqual(team.action, 'warn');
+  });
+});

package/compiler/__tests__/diversity-score.test.js

@@ -0,0 +1,117 @@
+/**
+ * Diversity score for Design-It-Twice mode.
+ *
+ * Computes pairwise Jaccard similarity over feature vectors of N designs.
+ * Returns 1 - mean(similarity).
+ *
+ * Used by brainstorm v0.6 Step 3.5 to gate re-spawning when designs are too similar.
+ */
+
+import assert from 'node:assert';
+import { describe, test } from 'node:test';
+
+function jaccard(a, b) {
+  const setA = new Set(a);
+  const setB = new Set(b);
+  const intersect = new Set([...setA].filter((x) => setB.has(x)));
+  const union = new Set([...setA, ...setB]);
+  if (union.size === 0) return 1;
+  return intersect.size / union.size;
+}
+
+function diversityScore(designs) {
+  if (designs.length < 2) return 1;
+  const pairs = [];
+  for (let i = 0; i < designs.length; i++) {
+    for (let j = i + 1; j < designs.length; j++) {
+      pairs.push(jaccard(designs[i], designs[j]));
+    }
+  }
+  const mean = pairs.reduce((a, b) => a + b, 0) / pairs.length;
+  return 1 - mean;
+}
+
+// Encoding: a feature vector is a list of feature tokens.
+// Examples:
+//   ["methods:1", "returns:1", "adapters:0", "deps:1", "paradigm:minimal", "async:no", "stream:no"]
+//   ["methods:8", "returns:5", "adapters:3", "deps:5", "paradigm:extensible", "async:yes", "stream:yes"]
+
+describe('diversity score', () => {
+  test('identical designs return diversity 0', () => {
+    const d1 = ['methods:3', 'paradigm:minimal'];
+    const d2 = ['methods:3', 'paradigm:minimal'];
+    assert.strictEqual(diversityScore([d1, d2]), 0);
+  });
+
+  test('disjoint designs return diversity 1', () => {
+    const d1 = ['methods:3', 'paradigm:minimal'];
+    const d2 = ['methods:8', 'paradigm:extensible'];
+    assert.strictEqual(diversityScore([d1, d2]), 1);
+  });
+
+  test('half-overlap returns diversity 0.5', () => {
+    const d1 = ['methods:3', 'paradigm:minimal'];
+    const d2 = ['methods:3', 'paradigm:extensible'];
+    // jaccard = 1/3 (intersection {methods:3}, union {methods:3, paradigm:minimal, paradigm:extensible})
+    // diversity = 1 - 1/3 = 0.6667
+    const diversity = diversityScore([d1, d2]);
+    assert.ok(Math.abs(diversity - 0.6667) < 0.001, `expected ~0.6667, got ${diversity}`);
+  });
+
+  test('three radically different designs pass 0.6 floor', () => {
+    const c1 = ['methods:2', 'returns:1', 'paradigm:minimal', 'adapters:0', 'async:no'];
+    const c2 = ['methods:8', 'returns:5', 'paradigm:extensible', 'adapters:0', 'async:yes'];
+    const c4 = ['methods:3', 'returns:2', 'paradigm:ports-adapters', 'adapters:2', 'async:no'];
+    const diversity = diversityScore([c1, c2, c4]);
+    assert.ok(diversity >= 0.6, `expected >=0.6, got ${diversity}`);
+  });
+
+  test('three near-identical designs fail 0.4 floor', () => {
+    const a = ['methods:3', 'returns:1', 'paradigm:minimal'];
+    const b = ['methods:3', 'returns:1', 'paradigm:minimal'];
+    const c = ['methods:3', 'returns:1', 'paradigm:minimal'];
+    const diversity = diversityScore([a, b, c]);
+    assert.ok(diversity < 0.4, `expected <0.4, got ${diversity}`);
+  });
+
+  test('marginal designs land in 0.4-0.59 zone (warn tier)', () => {
+    // 6/9 features shared between each pair → jaccard ≈ 0.50, diversity ≈ 0.50
+    const a = ['m:3', 'r:1', 'p:m', 'a:0', 'q:x', 'e:y'];
+    const b = ['m:3', 'r:1', 'p:m', 'a:0', 'q:x', 'e:z'];
+    const c = ['m:3', 'r:1', 'p:m', 'a:0', 'q:y', 'e:z'];
+    const diversity = diversityScore([a, b, c]);
+    assert.ok(diversity >= 0.3 && diversity < 0.6, `expected 0.3-0.59, got ${diversity}`);
+  });
+
+  test('single design returns diversity 1 (degenerate)', () => {
+    assert.strictEqual(diversityScore([['x']]), 1);
+  });
+
+  test('four designs (when C4 included) — diverse set passes', () => {
+    const c1 = ['methods:2', 'paradigm:minimal'];
+    const c2 = ['methods:8', 'paradigm:extensible'];
+    const c3 = ['methods:1', 'paradigm:default-light'];
+    const c4 = ['methods:3', 'paradigm:ports-adapters'];
+    const diversity = diversityScore([c1, c2, c3, c4]);
+    assert.ok(diversity >= 0.6, `expected >=0.6, got ${diversity}`);
+  });
+});
+
+describe('threshold gate', () => {
+  test('floor 0.4 — below triggers re-spawn', () => {
+    const FLOOR = 0.4;
+    const lowDiversity = 0.3;
+    assert.strictEqual(lowDiversity < FLOOR, true);
+  });
+
+  test('threshold 0.6 — proceed without warning', () => {
+    const THRESHOLD = 0.6;
+    const goodDiversity = 0.7;
+    assert.strictEqual(goodDiversity >= THRESHOLD, true);
+  });
+
+  test('warn zone 0.4-0.59 — surface to user', () => {
+    const value = 0.5;
+    assert.ok(value >= 0.4 && value < 0.6);
+  });
+});

package/compiler/__tests__/improve-architecture.test.js

@@ -0,0 +1,171 @@
+/**
+ * improve-architecture skill — structural and vocabulary tests.
+ *
+ * Validates:
+ *   - SKILL.md parses, version 0.1.0, layer L2, model opus
+ *   - Required reference files exist (language, deepening, interface-design, scoring)
+ *   - evals.md exists with >=4 evals across categories
+ *   - Vocabulary discipline: skill body + references do NOT use banned aliases
+ *   - Proposal payload schema shape (sample YAML in SKILL.md parses)
+ */
+
+import assert from 'node:assert';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { describe, test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+import { parseSkill } from '../parser.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SKILL_DIR = path.resolve(__dirname, '../../skills/improve-architecture');
+
+const REQUIRED_FILES = [
+  'SKILL.md',
+  'references/language.md',
+  'references/deepening.md',
+  'references/interface-design.md',
+  'references/scoring.md',
+  'evals.md',
+];
+
+// --- Files exist ---
+
+describe('improve-architecture file presence', () => {
+  for (const f of REQUIRED_FILES) {
+    test(`${f} exists`, () => {
+      const p = path.join(SKILL_DIR, f);
+      assert.ok(existsSync(p), `missing: ${f}`);
+    });
+  }
+});
+
+// --- SKILL.md parses correctly ---
+
+test('SKILL.md frontmatter — name, version, layer, model', () => {
+  const skillPath = path.join(SKILL_DIR, 'SKILL.md');
+  const parsed = parseSkill(readFileSync(skillPath, 'utf-8'));
+  assert.strictEqual(parsed.frontmatter.name, 'improve-architecture');
+  assert.strictEqual(parsed.frontmatter.metadata.version, '0.1.0');
+  assert.strictEqual(parsed.frontmatter.metadata.layer, 'L2');
+  assert.strictEqual(parsed.frontmatter.metadata.model, 'opus');
+});
+
+test('SKILL.md emit includes architecture.shallow.flagged + architecture.deletion.passed', () => {
+  const skillPath = path.join(SKILL_DIR, 'SKILL.md');
+  const content = readFileSync(skillPath, 'utf-8');
+  assert.ok(/emit:.*architecture\.shallow\.flagged/.test(content), 'emits architecture.shallow.flagged');
+  assert.ok(/emit:.*architecture\.deletion\.passed/.test(content), 'emits architecture.deletion.passed');
+});
+
+// --- Required reference content ---
+
+test('language.md defines all 8 controlled terms', () => {
+  const content = readFileSync(path.join(SKILL_DIR, 'references/language.md'), 'utf-8');
+  const required = ['Module', 'Interface', 'Implementation', 'Depth', 'Seam', 'Adapter', 'Leverage', 'Locality'];
+  for (const term of required) {
+    // Each term should appear as a heading line `### Term`
+    assert.ok(new RegExp(`^### ${term}\\b`, 'm').test(content), `language.md missing heading for "${term}"`);
+  }
+});
+
+test('deepening.md lists all 4 dependency categories', () => {
+  const content = readFileSync(path.join(SKILL_DIR, 'references/deepening.md'), 'utf-8');
+  for (const cat of ['In-process', 'Local-substitutable', 'Remote-owned', 'True-external']) {
+    assert.ok(content.includes(cat), `deepening.md missing dependency category "${cat}"`);
+  }
+});
+
+test('scoring.md provides numeric rubric for depth/leverage/locality', () => {
+  const content = readFileSync(path.join(SKILL_DIR, 'references/scoring.md'), 'utf-8');
+  for (const metric of ['## Depth (1–5)', '## Leverage (1–5)', '## Locality (1–5)']) {
+    assert.ok(content.includes(metric), `scoring.md missing section "${metric}"`);
+  }
+  // Deletion test verdict enum
+  for (const verdict of ['vanish', 'concentrate', 'redistribute']) {
+    assert.ok(content.includes(verdict), `scoring.md missing deletion-test verdict "${verdict}"`);
+  }
+});
+
+// --- Eval coverage ---
+
+test('evals.md has >=4 evals across categories', () => {
+  const content = readFileSync(path.join(SKILL_DIR, 'evals.md'), 'utf-8');
+  const evalMatches = content.match(/^## Eval: E\d+/gm) || [];
+  assert.ok(evalMatches.length >= 4, `expected >=4 evals, found ${evalMatches.length}`);
+
+  for (const cat of ['happy-path', 'edge-case', 'adversarial', 'jailbreak']) {
+    assert.ok(content.includes(cat), `evals.md missing category "${cat}"`);
+  }
+});
+
+// --- Vocabulary discipline: banned aliases in narrative prose ---
+
+describe('vocabulary discipline', () => {
+  // Skip narrative scan inside reference files that explicitly enumerate banned terms
+  // (language.md lists "Avoid:" rules — those mentions are intentional)
+  const SKIPPED_FILES = ['references/language.md'];
+
+  // Banned alias terms in skill narrative.
+  // We allow them inside fenced code blocks AND inside lines starting with "Avoid:" or "Banned"
+  // to permit legitimate doctrine prose ("don't say boundary").
+  const BANNED_ALIASES = ['boundary', 'component', 'service'];
+
+  for (const f of REQUIRED_FILES) {
+    if (SKIPPED_FILES.includes(f) || f === 'evals.md') continue;
+    test(`${f} narrative has no banned aliases`, () => {
+      const content = readFileSync(path.join(SKILL_DIR, f), 'utf-8');
+      const lines = content.split('\n');
+      let inFence = false;
+      const violations = [];
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim().startsWith('```')) {
+          inFence = !inFence;
+          continue;
+        }
+        if (inFence) continue;
+        // Skip lines that explicitly call out banned terms
+        const trimmed = line.trim();
+        if (
+          trimmed.startsWith('*Avoid*') ||
+          trimmed.startsWith('Avoid:') ||
+          trimmed.startsWith('Banned') ||
+          trimmed.startsWith('- **') || // banned-framings list items
+          /["“”'].*("|”|')\s*$/.test(trimmed) || // quoted phrases like "service"
+          line.includes('banned ') // doctrine sentences mentioning banned X
+        ) {
+          continue;
+        }
+        for (const bad of BANNED_ALIASES) {
+          // Match whole word, not substring (so "microservice" wouldn't trigger "service" only when it's a standalone word)
+          if (new RegExp(`\\b${bad}\\b`, 'i').test(line) && !line.includes(`"${bad}"`)) {
+            violations.push(`${f}:${i + 1}: ${line.trim()}`);
+            break;
+          }
+        }
+      }
+      assert.deepStrictEqual(violations, [], `vocabulary violations in ${f}:\n${violations.join('\n')}`);
+    });
+  }
+});
+
+// --- Proposal payload sample is parseable ---
+
+test('SKILL.md sample proposal payload is well-formed YAML-ish', () => {
+  const content = readFileSync(path.join(SKILL_DIR, 'SKILL.md'), 'utf-8');
+  // Find the architecture.proposal block
+  const match = content.match(/architecture\.proposal:[\s\S]*?(?=\n```|\n\n##)/);
+  assert.ok(match, 'SKILL.md missing architecture.proposal sample');
+  const block = match[0];
+  // Must include required fields
+  for (const field of [
+    'module_path:',
+    'current:',
+    'target:',
+    'dependency_category:',
+    'suggested_seam:',
+    'adapters_planned:',
+  ]) {
+    assert.ok(block.includes(field), `proposal payload missing field "${field}"`);
+  }
+});