@rune-kit/rune 2.12.3 → 2.14.0

package/README.md

@@ -5,7 +5,7 @@
 <p align="center">
   <strong>Less skills. Deeper connections.</strong><br>
   A lean, interconnected skill ecosystem for AI coding assistants.<br>
-  62 skills · 215+ mesh connections · 8 platforms · MIT
+  63 skills · 215+ mesh connections · 8 platforms · MIT
 </p>
 
 <p align="center">
@@ -23,7 +23,7 @@
 
 Most skill ecosystems are either **too many isolated skills** (540+ that don't talk to each other) or **rigid pipelines** (A → B → C, if B fails everything stops).
 
-Rune is a **mesh** — 62 skills with 215+ connections across a 5-layer architecture. Skills call each other bidirectionally, forming resilient workflows that adapt when things go wrong.
+Rune is a **mesh** — 63 skills with 215+ connections across a 5-layer architecture. Skills call each other bidirectionally, forming resilient workflows that adapt when things go wrong.
 
 ```
 Pipeline:  A → B → C → D         (B fails = stuck)
@@ -83,7 +83,26 @@ _Methodology: Claude Code CLI headless mode (`claude -p --output-format json`),
 
 ---
 
-## What's New (v2.12.0 — Auto-Discipline)
+## What's New (v2.14.0 — Deep Modules)
+
+- **`improve-architecture` skill (NEW L2, opus)** — surfaces deepening opportunities with controlled vocabulary (Module / Interface / Implementation / Depth / Seam / Adapter / Leverage / Locality), numeric depth-leverage-locality scoring (1–5 each), 4 dependency categories that drive test strategy, and structured proposal payloads `surgeon` consumes programmatically. Ban-listed aliases ("boundary", "component", "service", "layer") enforced by compiler test.
+- **TDD vertical-slicing HARD-GATE** — `test` v1.3.0 catches "horizontal slicing" (5 tests written before any GREEN) with a `bulk_test_count <= 1` rule, mandates commit-pair audit trail (`test:` + `feat:` per cycle) verified by `completion-gate`, flags shape-words in test names ("returns", "has property", "is defined") as candidates for behavior-verb rewrite.
+- **`.out-of-scope/` knowledge base** — `ba` v0.11.0 reads it on intake (lexical similarity matching, ≥0.8 confidence surfaces prior rejections), `review-intake` v1.2.0 writes/appends it on every OUT OF SCOPE verdict. Stops the "agent re-litigates a rejected feature next session" failure mode. YAML frontmatter for machine parsing + Markdown body for humans.
+- **CONTEXT.md inline-sharpen + ADR 3-criteria gate** — `ba` builds the project glossary as terms emerge; cross-references user assertions against the codebase via grep before recording. `journal` v0.4.0 only opens an ADR when `reversibility + surprisingness + tradeoff_strength >= 11` AND each axis ≥ 3, with a counter-test (rejected alternative) that can't be faked. Filename includes the score: `ADR-007-postgres-write-model-s13.md`.
+- **Agent Brief durability** — `context-pack` v0.2.0 adds mandatory `### Out of scope` and `### Type Surface (durable)` sections, runs regex smell tests pre-emit (BLOCK on file:line / "line N" / narrative paths; WARN on bare `src/` mentions), enforces behavioral-verb whitelist on Acceptance Criteria. Stops handoff briefs from rotting when files get renamed.
+- **Design-It-Twice mode** — `brainstorm` v0.6.0 spawns 3-4 parallel subagents, each pinned to one constraint (minimize / maximize-flexibility / optimize-common-case / ports-and-adapters), computes diversity score across feature vectors (Jaccard-based, floor 0.4), re-spawns once if too similar, presents sequentially with an opinionated recommendation. "It depends" is BLOCKED.
+- **Zoom-out + explore-first micro-utilities** — `scout` v0.4.0 listens for `agent.stuck` (emitted by `fix` after 2 failed attempts and `debug` after 3 disproved hypotheses), produces a 3-layer Mermaid map (target / siblings / callers, capped at 8 each). `ba` v0.11.0 explore-first HARD-GATE: every elicitation question requires prior tool-call evidence (Read/Glob/Grep) — no more asking "what stack?" when `package.json` answers it.
+- **5 new mesh signals** — `tdd.horizontal.violation`, `architecture.shallow.flagged`, `architecture.deletion.passed`, `outofscope.match`, `agent.stuck`.
+- **1,260 tests** — +81 from v2.13.0 across 7 new test files covering schema validation, vocabulary discipline, ADR scoring, smell-test regex, diversity formula, zoom-out output.
+
+### Previous (v2.13.0 — Script Contract + Media Pack)
+
+- **`@rune-pro/media` pack v1.0.0** — new Pro pack: raster image generation across 5 providers (Codex CLI, DALL-E, Replicate, Stability AI, local SD), prompt engineering with 4-gate safety check (trademark, public-figure, prompt-injection, uncanny-precondition), batch asset pipeline with multi-resolution variants + WebP/AVIF conversion + EXIF strip.
+- **`sentinel-env` v0.3.0** — 9-tier binary detection for hard-dependency checks.
+- **`skill-forge` v1.8.0** — new Phase 5.25 "Script Contract" — helper scripts must follow stdout=paths / stderr=diagnostics / `--json` opt-in / semantic exit codes. HARD-GATE on pre-ship verification.
+- **OpenClaw adapter** — `generateManifest` now declares `artifactConvention`.
+
+### Previous (v2.12.0 — Auto-Discipline)
 
 - **Runtime auto-discipline** — `rune hooks install` wires native hooks on Claude Code, Cursor, Windsurf, Antigravity so `preflight`, `sentinel`, `completion-gate` auto-fire before tool use. No more "remember to invoke the skill."
 - **Three presets** — `strict` (blocking gates), `gentle` (warnings, default), `off` (uninstall). Idempotent install / uninstall with full restore of user hooks.
@@ -150,7 +169,7 @@ cook ───emit:phase.complete────→ session-bridge
 
 ## What Rune Is (and Isn't)
 
-Rune started as a **Claude Code plugin** and now compiles to **every major AI IDE**. Same 62 skills, same mesh connections, same workflows — zero knowledge loss across platforms.
+Rune started as a **Claude Code plugin** and now compiles to **every major AI IDE**. Same 63 skills, same mesh connections, same workflows — zero knowledge loss across platforms.
 
 | | Rune Provides | Claude Code Provides |
 |---|---|---|
@@ -202,7 +221,7 @@ npx @rune-kit/rune init --platform windsurf
 npx @rune-kit/rune init --platform antigravity
 ```
 
-This compiles all 62 skills into your IDE's rules format. Same knowledge, same workflows.
+This compiles all 63 skills into your IDE's rules format. Same knowledge, same workflows.
 
 ### Platform Comparison
 
@@ -548,17 +567,32 @@ npx @rune-kit/rune doctor
 
 See [docs/MULTI-PLATFORM.md](docs/MULTI-PLATFORM.md) for the full architecture.
 
+## Documentation
+
+| Doc | What's inside |
+|-----|---------------|
+| [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md) | Your first 5 minutes with Rune — install to first `/rune cook` |
+| [`docs/SKILLS.md`](docs/SKILLS.md) | All 63 skills, searchable by intent and layer |
+| [`docs/SIGNALS.md`](docs/SIGNALS.md) | Canonical signal inventory — 25 events, emit/listen graph |
+| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | 5-layer mesh architecture reference |
+| [`docs/VISION.md`](docs/VISION.md) | Philosophy — what Rune is and isn't |
+| [`docs/HOOKS.md`](docs/HOOKS.md) | Auto-discipline hooks per platform |
+| [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) | Common issues + fixes |
+| [`CONTRIBUTING.md`](CONTRIBUTING.md) | How to contribute skills, packs, fixes |
+| [`CHANGELOG.md`](CHANGELOG.md) | Release history |
+| [`ROADMAP.md`](ROADMAP.md) | What's next |
+
 ## Numbers
 
 ```
 Core Skills:       62 (L0: 1 │ L1: 5 │ L2: 29 │ L3: 27)
 Extension Packs:   14 free + 5 pro + 4 business
 Mesh Connections:  215+ cross-references
-Mesh Signals:      23 signals across 62 skills (emit/listen graph)
+Mesh Signals:      25 signals across 63 skills (emit/listen graph)
 Connections/Skill: 3.4 avg
 Platforms:         8 (Claude Code, Cursor, Windsurf, Antigravity, Codex, OpenCode, OpenClaw, Generic)
 Compiler:          ~1400 LOC (parser + 8 transforms + 8 adapters + CLI)
-Tests:             946 (compiler + signals + status + visualizer + hooks + scripts)
+Tests:             1,152+ (compiler + signals + status + visualizer + hooks + scripts + tier-hooks)
 Pack Depth:        23 packs total (14 free + 5 pro + 4 business, all free packs rated Deep)
 ```
 

package/compiler/__tests__/adr-scoring.test.js

@@ -0,0 +1,91 @@
+/**
+ * ADR scoring gate — verify the 3-criteria threshold logic.
+ *
+ * The gate: open_adr = (sum >= 11) AND (each axis >= 3)
+ *   - Prevents single-axis cheating
+ *   - Counter-test (rejected alternative) is enforced at write time, not numerically
+ *
+ * Also validates ADR filename pattern includes the score.
+ */
+
+import assert from 'node:assert';
+import { describe, test } from 'node:test';
+
+function shouldOpenAdr({ reversibility, surprisingness, tradeoff_strength }) {
+  const sum = reversibility + surprisingness + tradeoff_strength;
+  const minAxis = Math.min(reversibility, surprisingness, tradeoff_strength);
+  return sum >= 11 && minAxis >= 3;
+}
+
+const ADR_FILENAME_PATTERN = /^ADR-\d{3}-[a-z][a-z0-9]*(-[a-z0-9]+)*-s(\d{1,2})\.md$/;
+
+describe('ADR scoring gate', () => {
+  test('opens ADR when sum >= 11 and all axes >= 3', () => {
+    assert.strictEqual(shouldOpenAdr({ reversibility: 4, surprisingness: 4, tradeoff_strength: 3 }), true);
+    assert.strictEqual(shouldOpenAdr({ reversibility: 5, surprisingness: 5, tradeoff_strength: 5 }), true);
+    assert.strictEqual(shouldOpenAdr({ reversibility: 4, surprisingness: 3, tradeoff_strength: 4 }), true);
+  });
+
+  test('blocks when sum < 11', () => {
+    assert.strictEqual(
+      shouldOpenAdr({ reversibility: 3, surprisingness: 3, tradeoff_strength: 3 }),
+      false,
+      'sum=9 should block',
+    );
+    assert.strictEqual(
+      shouldOpenAdr({ reversibility: 4, surprisingness: 4, tradeoff_strength: 2 }),
+      false,
+      'sum=10 should block (also violates min-axis rule)',
+    );
+  });
+
+  test('blocks single-axis cheating: 5+5+1 = 11 sum but axis=1 fails min-axis rule', () => {
+    assert.strictEqual(shouldOpenAdr({ reversibility: 5, surprisingness: 5, tradeoff_strength: 1 }), false);
+    assert.strictEqual(shouldOpenAdr({ reversibility: 5, surprisingness: 1, tradeoff_strength: 5 }), false);
+    assert.strictEqual(shouldOpenAdr({ reversibility: 1, surprisingness: 5, tradeoff_strength: 5 }), false);
+  });
+
+  test('boundary: sum=11 with all axes = 3 — Wait, 3+3+3 = 9, not 11. Min sum with each axis >=3 is 9. So sum=11 implies at least one axis is 4', () => {
+    // 3+3+5 = 11, all axes >= 3, should open
+    assert.strictEqual(shouldOpenAdr({ reversibility: 3, surprisingness: 3, tradeoff_strength: 5 }), true);
+  });
+
+  test('borderline cases (sum 8-10) all block — these go to conventions, not ADRs', () => {
+    for (let r = 1; r <= 5; r++) {
+      for (let s = 1; s <= 5; s++) {
+        for (let t = 1; t <= 5; t++) {
+          const sum = r + s + t;
+          const result = shouldOpenAdr({ reversibility: r, surprisingness: s, tradeoff_strength: t });
+          if (sum >= 8 && sum <= 10) {
+            assert.strictEqual(result, false, `sum=${sum} (${r}/${s}/${t}) should block`);
+          }
+        }
+      }
+    }
+  });
+});
+
+describe('ADR filename pattern', () => {
+  test('valid filenames with score', () => {
+    assert.ok(ADR_FILENAME_PATTERN.test('ADR-007-postgres-write-model-s13.md'));
+    assert.ok(ADR_FILENAME_PATTERN.test('ADR-001-monorepo-s12.md'));
+    assert.ok(ADR_FILENAME_PATTERN.test('ADR-042-event-sourced-orders-s14.md'));
+  });
+
+  test('rejects filename without score suffix', () => {
+    assert.ok(!ADR_FILENAME_PATTERN.test('ADR-007-postgres-write-model.md'));
+  });
+
+  test('rejects non-sequential ADR id format', () => {
+    assert.ok(!ADR_FILENAME_PATTERN.test('ADR-7-postgres-s11.md'));
+  });
+
+  test('rejects PascalCase slug', () => {
+    assert.ok(!ADR_FILENAME_PATTERN.test('ADR-007-PostgresWriteModel-s13.md'));
+  });
+
+  test('extracts score from filename', () => {
+    const m = 'ADR-007-postgres-write-model-s13.md'.match(ADR_FILENAME_PATTERN);
+    assert.strictEqual(parseInt(m[2], 10), 13);
+  });
+});

package/compiler/__tests__/context-md-format.test.js

@@ -0,0 +1,180 @@
+/**
+ * CONTEXT.md format — validates the project glossary structure.
+ *
+ * Lazy creation rule: empty/absent CONTEXT.md is OK; the validator only runs on existing files.
+ *
+ * Required sections: # Project Glossary heading, ## Language table, ## Relationships
+ * Optional sections: ## Example dialogue, ## Flagged ambiguities
+ */
+
+import assert from 'node:assert';
+import { describe, test } from 'node:test';
+
+function validateContextMd(content) {
+  const issues = [];
+
+  if (!/^# .+/m.test(content.split('\n')[0] || '')) {
+    issues.push('first line must be H1 (# Title)');
+  }
+
+  if (!/## Language/.test(content)) {
+    issues.push('missing ## Language section');
+  }
+
+  if (!/## Relationships/.test(content)) {
+    issues.push('missing ## Relationships section');
+  }
+
+  // Validate Language table shape if present
+  const langMatch = content.match(/## Language\s*\n([\s\S]*?)(?=\n## |\n# |$)/);
+  if (langMatch) {
+    const tableLines = langMatch[1].split('\n').filter((l) => l.trim().startsWith('|'));
+    if (tableLines.length < 3) {
+      issues.push('## Language section must contain a Markdown table with header + separator + >=1 row');
+    } else {
+      // Header should mention Term, Definition, Aliases, Status
+      const header = tableLines[0].toLowerCase();
+      const requiredColumns = [
+        { lower: 'term', label: 'Term' },
+        { lower: 'definition', label: 'Definition' },
+        { lower: 'aliases', label: 'Aliases' },
+        { lower: 'status', label: 'Status' },
+      ];
+      for (const col of requiredColumns) {
+        if (!header.includes(col.lower)) {
+          issues.push(`Language table header missing column: ${col.label}`);
+        }
+      }
+      // Each row should have a status field with valid value
+      const validStatuses = ['canonical', 'pending', 'conflicted'];
+      for (let i = 2; i < tableLines.length; i++) {
+        const row = tableLines[i];
+        const cells = row
+          .split('|')
+          .map((c) => c.trim())
+          .filter(Boolean);
+        if (cells.length >= 4) {
+          const status = cells[3].toLowerCase();
+          if (!validStatuses.includes(status)) {
+            issues.push(`row "${cells[0]}" has invalid status "${status}"`);
+          }
+        }
+      }
+    }
+  }
+
+  return issues;
+}
+
+describe('CONTEXT.md format', () => {
+  test('valid context passes', () => {
+    const content = `# Project Glossary
+
+## Language
+
+| Term | Definition | Aliases to avoid | Status |
+|------|------------|-------------------|--------|
+| **Order** | A customer's request to purchase items | Purchase, transaction | canonical |
+| **Invoice** | A request for payment | Bill | canonical |
+
+## Relationships
+
+- An **Order** produces one or more **Invoices**
+
+## Flagged ambiguities
+
+- "account" was used for both Customer and User — resolved.
+`;
+    assert.deepStrictEqual(validateContextMd(content), []);
+  });
+
+  test('rejects content without H1', () => {
+    const content = `## Language
+| Term | Definition | Aliases | Status |
+|------|------------|---------|--------|
+| **X** | y | z | canonical |
+## Relationships
+- A
+`;
+    const issues = validateContextMd(content);
+    assert.ok(
+      issues.some((i) => i.includes('H1')),
+      'should require H1',
+    );
+  });
+
+  test('rejects missing Language section', () => {
+    const content = `# Project Glossary
+## Relationships
+- A
+`;
+    const issues = validateContextMd(content);
+    assert.ok(
+      issues.some((i) => i.includes('Language')),
+      'should require Language section',
+    );
+  });
+
+  test('rejects missing Relationships section', () => {
+    const content = `# Project Glossary
+## Language
+| Term | Definition | Aliases | Status |
+|------|------------|---------|--------|
+| **X** | y | z | canonical |
+`;
+    const issues = validateContextMd(content);
+    assert.ok(
+      issues.some((i) => i.includes('Relationships')),
+      'should require Relationships section',
+    );
+  });
+
+  test('rejects invalid status value', () => {
+    const content = `# Project Glossary
+## Language
+| Term | Definition | Aliases | Status |
+|------|------------|---------|--------|
+| **Order** | y | z | provisional |
+## Relationships
+- A
+`;
+    const issues = validateContextMd(content);
+    assert.ok(
+      issues.some((i) => i.includes('invalid status')),
+      'should reject status outside canonical|pending|conflicted',
+    );
+  });
+
+  test('accepts pending and conflicted statuses', () => {
+    const content = `# Project Glossary
+## Language
+| Term | Definition | Aliases | Status |
+|------|------------|---------|--------|
+| **Order** | y | z | pending |
+| **Invoice** | y | z | conflicted |
+## Relationships
+- A
+`;
+    assert.deepStrictEqual(validateContextMd(content), []);
+  });
+
+  test('rejects table missing required columns', () => {
+    const content = `# Project Glossary
+## Language
+| Term | Definition |
+|------|------------|
+| **Order** | y |
+## Relationships
+- A
+`;
+    const issues = validateContextMd(content);
+    assert.ok(
+      issues.some((i) => i.includes('Aliases')),
+      'should require Aliases column',
+    );
+    assert.ok(
+      issues.some((i) => i.includes('Status')),
+      'should require Status column',
+    );
+  });
+});

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);
+  });
+});