@rune-kit/rune 2.14.0 → 2.16.0

package/README.md

@@ -83,17 +83,37 @@ _Methodology: Claude Code CLI headless mode (`claude -p --output-format json`),
 
 ---
 
-## 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.
+## What's New (v2.16.0 — Skill Enrichment + Triage Workflow + Output Modes)
+
+- **`debug` v1.2.0 — Step 0: Build Feedback Loop** — 10-rank ladder (failing test → curl → CLI snapshot → headless browser → trace replay → throwaway harness → fuzz → bisection → differential → HITL script). Codifies "the loop is the speed limit" — a fast deterministic pass/fail signal turns debugging into mechanical bisection. Skip if repro is already < 5s and deterministic; > 10 min loop construction triggers 3-Fix Escalation (architecture is the problem).
+- **`plan` v1.6.0 — Vertical Slice Mode** — tracer-bullet task decomposition. Each task = end-to-end path through schema + API + UI + test, demoable on its own. AFK / HITL classification. Stops "horizontal layer" planning that blocks on the slowest layer.
+- **`context-engine` v1.2.0 — Caveman Output Mode** — auto-activates on context ORANGE / RED (or `/caveman`). Strips filler / articles / hedging / pleasantries while preserving full technical accuracy (~75% output reduction). Auto-clarity exceptions for security warnings, destructive-action confirmations, multi-step sequences, root-cause diagnosis.
+- **`ba` v0.13.0 — Synthesis Mode + Out-of-Scope WRITE** — when prior conversation has rich context (pasted spec, > 1000 words, continuation session), extract Requirements Document with source citations and confirm instead of re-interviewing. Step 1.6 closes the `.out-of-scope/` write loop: explicit mid-elicitation rejections produce a durable `.out-of-scope/<slug>.md` record so future sessions don't re-litigate.
+- **`context-pack` v0.3.0 — Agent Brief Variant** — durable handoff format for AFK agents (issue tracker queues, autopilot multi-session work). Behavioral over procedural; type names over file:line. Survives codebase drift between handoff and execution.
+- **`review-intake` v1.3.0 — Issue Triage Mode** — new mode for issue tracker items (PR Review remains default). State machine: needs-triage → needs-info / ready-for-agent / ready-for-human / wontfix. Repro-first HARD-GATE for bugs (calls `debug` Step 0 if multi-component). Vague issues route to `ba` Synthesis Mode for grilling. AGENT-BRIEF emission for `ready-for-agent`.
+- **5 new mesh signals** — `output.density.set`, `triage.classified`, `agent.brief.ready`, `outofscope.recorded` + `EXTERNAL_TRIGGER_SIGNALS` whitelist concept (symmetric to `INTENTIONAL_BROADCAST_SIGNALS`).
+- **Validator cleanups** — `validate-skills.js` Done-When regex relaxed (scope-aware, supports mode-based subsections); 9 pre-existing validation errors cleaned. `validate-signals.js` gained `EXTERNAL_TRIGGER_SIGNALS` set.
+- **Provenance** — second graft pass from [`mattpocock/skills`](https://github.com/mattpocock/skills) (MIT). Round 1 had silently grafted 7 patterns (improve-architecture, CONTEXT.md, design-it-twice, zoom-out, oracle-mode, grill, out-of-scope); Round 2 + 2b documented + extended.
+
+### Previous (v2.15.0 — Second Opinion + Cross-Provider + Routing Clarity)
+
+- **`adversary` v0.2.0 — Mode: oracle** — when `agent.stuck` fires from `debug` (3 disproved hypotheses) or `fix` (2+ failed attempts), oracle-mode dispatches a stateless second-model pass with explicit "no prior context" framing. Bundle format is regex-validated (`[SYSTEM]` invariant role-priming + `[USER]` template + `### File N`), token-capped (100k bundle, 4k per file, 12 files max), citation-required reply contract. Secrets auto-redacted. Breaks the confirmation-bias loop that scout's zoom-out (structural pivot) cannot.
+- **`session-bridge` v0.8.0 — Detach Mode** — async escalation primitive. Heavy-model second-opinion calls (1-10 min wall time) no longer block the primary agent. `.rune/oracle-pending/<sessionId>.json` is the rendezvous file; idempotent dispatch (bundleHash-keyed); 10min default timeout; 24h orphan cleanup on session start. `cook` Phase 4 and `team` Phase 3 reattach via filesystem poll between adjacent tasks.
+- **`context-engine` v1.1.0 — Mode: preview** — pre-flight cost gate. Caller emits `context.preview` BEFORE bundle build with file list + estimated tokens (chars × 0.25). Per-caller thresholds: adversary 50k/100k, team 30k/80k (per worker), review 40k/100k, audit 60k/120k. Action enum `proceed | warn | block`. Override via `RUNE_CONTEXT_THRESHOLDS_<CALLER>`. Stops `team` parallel workstreams from silently blowing $20 of Opus tokens.
+- **Cross-provider model mapping** — 5 non-Anthropic adapters now translate `model: opus|sonnet|haiku` to provider-correct names. **codex** → gpt-5-pro / gpt-5 / gpt-5-mini. **antigravity** → gemini-3-pro / gemini-3-flash / gemini-3-flash-lite. **opencode / openclaw / generic** → tier:heavy / tier:mid / tier:light (provider-agnostic). claude / cursor / windsurf remain no-op (Anthropic backend understands native names).
+- **Routing clarity sweep** — all 63 SKILL.md descriptions now double-quoted (YAML safety). 13 ambiguous-name skills got explicit "Use when…" routing hints so skill-router doesn't have to guess: ba, completion-gate, constraint-check, doc-processor, integrity-check, logic-guardian, onboard, preflight, sentinel-env, watchdog, worktree, hallucination-guard, mcp-builder.
+- **4 new mesh signals** — `oracle.dispatched`, `oracle.response`, `oracle.failed`, `context.preview`. All registered in Signal Catalog with full emit/listen mapping. `agent.stuck` listeners updated to include adversary in addition to scout.
+- **1,331 tests** — +71 from v2.14.0 across 5 new test files: adapter-model-mapping (18), oracle-bundle-format (19), oracle-pending-schema (16), context-preview-signal (13), skill-description-quality (5).
+
+### Previous (v2.14.0 — Deep Modules)
+
+- **`improve-architecture` skill (NEW L2, opus)** — controlled vocabulary (Module / Interface / Implementation / Depth / Seam / Adapter / Leverage / Locality), numeric depth-leverage-locality scoring (1–5 each), 4 dependency categories, structured proposal payloads.
+- **TDD vertical-slicing HARD-GATE** — `test` v1.3.0 catches "horizontal slicing" (5 tests before any GREEN), commit-pair audit trail, shape-test smell detector.
+- **`.out-of-scope/` knowledge base** — `ba` v0.11.0 reads, `review-intake` v1.2.0 writes. Stops re-litigation of rejected features.
+- **CONTEXT.md inline-sharpen + ADR 3-criteria gate** — `journal` v0.4.0 only opens an ADR when sum ≥ 11 + each axis ≥ 3.
+- **Agent Brief durability** — `context-pack` v0.2.0 regex smell tests block stale paths/line numbers.
+- **Design-It-Twice mode** — `brainstorm` v0.6.0 with constraint-pinned parallel subagents + diversity score gate.
+- **Zoom-out + explore-first micro-utilities** — `scout` v0.4.0 listens for `agent.stuck`; `ba` Step 2.0 HARD-GATE requires tool-call evidence.
 
 ### Previous (v2.13.0 — Script Contract + Media Pack)
 

package/compiler/__tests__/adapter-model-mapping.test.js

@@ -0,0 +1,152 @@
+/**
+ * Adapter model tier mapping (v2.15+) — verify non-Anthropic adapters
+ * translate `model: opus|sonnet|haiku` to provider-correct names while
+ * Anthropic-backed adapters (claude/cursor/windsurf) remain no-op.
+ *
+ * Validates:
+ *   - codex/antigravity emit concrete provider model names
+ *   - opencode/openclaw/generic emit semantic tier hints (provider-agnostic)
+ *   - claude/cursor/windsurf do NOT translate (no-op)
+ *   - Skills without `model:` produce no model line
+ *   - Unknown tier values pass through unchanged
+ */
+
+import assert from 'node:assert';
+import { describe, test } from 'node:test';
+import { getAdapter } from '../adapters/index.js';
+
+const baseSkill = {
+  name: 'cook',
+  description: 'Feature implementation orchestrator',
+  layer: 'L1',
+  group: 'orchestration',
+};
+
+describe('codex adapter model mapping', () => {
+  const codex = getAdapter('codex');
+
+  test('opus translates to gpt-5-pro', () => {
+    const header = codex.generateHeader({ ...baseSkill, model: 'opus' });
+    assert.match(header, /model: gpt-5-pro/);
+  });
+
+  test('sonnet translates to gpt-5', () => {
+    const header = codex.generateHeader({ ...baseSkill, model: 'sonnet' });
+    assert.match(header, /model: gpt-5(?!-)/);
+  });
+
+  test('haiku translates to gpt-5-mini', () => {
+    const header = codex.generateHeader({ ...baseSkill, model: 'haiku' });
+    assert.match(header, /model: gpt-5-mini/);
+  });
+
+  test('omitted model produces no model line', () => {
+    const header = codex.generateHeader({ ...baseSkill });
+    assert.doesNotMatch(header, /model:/);
+  });
+
+  test('unknown tier passes through unchanged', () => {
+    const header = codex.generateHeader({ ...baseSkill, model: 'custom-fine-tune' });
+    assert.match(header, /model: custom-fine-tune/);
+  });
+});
+
+describe('antigravity adapter model mapping', () => {
+  const antigravity = getAdapter('antigravity');
+
+  test('opus translates to gemini-3-pro', () => {
+    const header = antigravity.generateHeader({ ...baseSkill, model: 'opus' });
+    assert.match(header, /model: gemini-3-pro/);
+  });
+
+  test('sonnet translates to gemini-3-flash', () => {
+    const header = antigravity.generateHeader({ ...baseSkill, model: 'sonnet' });
+    assert.match(header, /model: gemini-3-flash(?!-)/);
+  });
+
+  test('haiku translates to gemini-3-flash-lite', () => {
+    const header = antigravity.generateHeader({ ...baseSkill, model: 'haiku' });
+    assert.match(header, /model: gemini-3-flash-lite/);
+  });
+});
+
+describe('opencode adapter model mapping (provider-agnostic)', () => {
+  const opencode = getAdapter('opencode');
+
+  test('opus translates to tier:heavy', () => {
+    const header = opencode.generateHeader({ ...baseSkill, model: 'opus' });
+    assert.match(header, /model: tier:heavy/);
+  });
+
+  test('sonnet translates to tier:mid', () => {
+    const header = opencode.generateHeader({ ...baseSkill, model: 'sonnet' });
+    assert.match(header, /model: tier:mid/);
+  });
+
+  test('haiku translates to tier:light', () => {
+    const header = opencode.generateHeader({ ...baseSkill, model: 'haiku' });
+    assert.match(header, /model: tier:light/);
+  });
+});
+
+describe('openclaw adapter model mapping (markdown header)', () => {
+  const openclaw = getAdapter('openclaw');
+
+  test('opus appears as tier:heavy in metadata line', () => {
+    const header = openclaw.generateHeader({ ...baseSkill, model: 'opus' });
+    assert.match(header, /model: tier:heavy/);
+  });
+
+  test('omitted model produces no model line', () => {
+    const header = openclaw.generateHeader({ ...baseSkill });
+    assert.doesNotMatch(header, /model:/);
+  });
+});
+
+describe('generic adapter model mapping (markdown header)', () => {
+  const generic = getAdapter('generic');
+
+  test('opus appears as tier:heavy in metadata line', () => {
+    const header = generic.generateHeader({ ...baseSkill, model: 'opus' });
+    assert.match(header, /model: tier:heavy/);
+  });
+});
+
+describe('Anthropic-native adapters are no-op for model field', () => {
+  test('claude generateHeader returns empty (passthrough)', () => {
+    const claude = getAdapter('claude');
+    const header = claude.generateHeader({ ...baseSkill, model: 'opus' });
+    assert.strictEqual(header, '');
+  });
+
+  test('cursor + windsurf do NOT rewrite anthropic tier names', () => {
+    const cursor = getAdapter('cursor');
+    const windsurf = getAdapter('windsurf');
+    const cursorHeader = cursor.generateHeader({ ...baseSkill, model: 'opus' });
+    const windsurfHeader = windsurf.generateHeader({ ...baseSkill, model: 'opus' });
+    assert.doesNotMatch(cursorHeader, /gpt-5/);
+    assert.doesNotMatch(cursorHeader, /gemini/);
+    assert.doesNotMatch(windsurfHeader, /gpt-5/);
+    assert.doesNotMatch(windsurfHeader, /gemini/);
+  });
+});
+
+describe('cross-adapter consistency', () => {
+  test('all 5 non-Anthropic adapters emit a model line for opus skills', () => {
+    const adapterNames = ['codex', 'antigravity', 'opencode', 'openclaw', 'generic'];
+    for (const name of adapterNames) {
+      const adapter = getAdapter(name);
+      const header = adapter.generateHeader({ ...baseSkill, model: 'opus' });
+      assert.match(header, /model: /, `${name} should emit a model line for opus skill`);
+    }
+  });
+
+  test('all 5 non-Anthropic adapters omit model line when skill has no model', () => {
+    const adapterNames = ['codex', 'antigravity', 'opencode', 'openclaw', 'generic'];
+    for (const name of adapterNames) {
+      const adapter = getAdapter(name);
+      const header = adapter.generateHeader({ ...baseSkill });
+      assert.doesNotMatch(header, /model:/, `${name} should NOT emit a model line for skill without model`);
+    }
+  });
+});

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__/oracle-bundle-format.test.js

@@ -0,0 +1,210 @@
+/**
+ * Adversary oracle-mode context bundle format — verify the regex-validated
+ * structure that adversary emits when dispatching to a second model.
+ *
+ * The bundle has 3 mandatory sections:
+ *   1. [SYSTEM] line with exact role-priming text
+ *   2. [USER] line with template-driven problem statement
+ *   3. ### File N: <path> blocks with normalized content
+ *
+ * Validates:
+ *   - System prompt is invariant (must match exact text)
+ *   - User section non-empty, within length bounds
+ *   - File headers numbered sequentially
+ *   - Hard caps enforced (12 files, 4k chars per file, 100k bundle)
+ *   - Forbidden content stripped (secrets redacted)
+ *   - Citation validation (reply must cite files in bundle)
+ */
+
+import assert from 'node:assert';
+import { describe, test } from 'node:test';
+
+const SYSTEM_LINE_REGEX =
+  /^\[SYSTEM\] You are Oracle, a focused one-shot problem solver\. You have NO prior context — assume zero project knowledge\. Cite file:line for every claim\. Reject any claim you cannot ground in the provided files\.$/;
+
+const USER_LINE_REGEX = /^\[USER\] .{20,2000}$/;
+
+const FILE_HEADER_REGEX = /^### File \d+: [^\n]+$/;
+
+const HARD_CAPS = {
+  bundleChars: 400_000,
+  perFileChars: 4_000,
+  fileCount: 12,
+  userMaxChars: 2_000,
+};
+
+function buildSystemLine() {
+  return '[SYSTEM] You are Oracle, a focused one-shot problem solver. You have NO prior context — assume zero project knowledge. Cite file:line for every claim. Reject any claim you cannot ground in the provided files.';
+}
+
+function buildUserLine(source, payload) {
+  if (source === 'debug') {
+    return `[USER] Agent stuck after ${payload.cycles} hypothesis cycles. Disproved: ${payload.disproved}. Error: ${payload.error}. What is the most likely root cause not yet considered?`;
+  }
+  if (source === 'fix') {
+    return `[USER] Agent stuck after ${payload.attempts} failed fix attempts on ${payload.file}. Each attempt's tests failed with: ${payload.testFailure}. What is the most likely cause of the test failure?`;
+  }
+  return `[USER] ${payload}`;
+}
+
+function buildBundle({ files = [], userLine, systemLine = buildSystemLine() }) {
+  const sections = [systemLine, '', userLine, ''];
+  files.forEach((f, i) => {
+    sections.push(`### File ${i + 1}: ${f.path}`);
+    sections.push(f.content);
+    sections.push('');
+  });
+  return sections.join('\n');
+}
+
+function validateBundle(bundle) {
+  const errors = [];
+  if (bundle.length > HARD_CAPS.bundleChars) errors.push('bundle_too_large');
+  const lines = bundle.split('\n');
+  const sysLine = lines.find((l) => l.startsWith('[SYSTEM]'));
+  if (!sysLine || !SYSTEM_LINE_REGEX.test(sysLine)) errors.push('invalid_system_line');
+  const userLine = lines.find((l) => l.startsWith('[USER]'));
+  if (!userLine || !USER_LINE_REGEX.test(userLine)) errors.push('invalid_user_line');
+  const fileHeaders = lines.filter((l) => l.startsWith('### File '));
+  if (fileHeaders.length > HARD_CAPS.fileCount) errors.push('too_many_files');
+  for (let i = 0; i < fileHeaders.length; i++) {
+    if (!FILE_HEADER_REGEX.test(fileHeaders[i])) errors.push(`invalid_file_header_${i}`);
+    const expectedNum = i + 1;
+    if (!fileHeaders[i].startsWith(`### File ${expectedNum}:`)) errors.push(`out_of_order_file_${i}`);
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+function redactSecrets(content) {
+  return content
+    .replace(/(api[_-]?key|secret|password|token)\s*[:=]\s*["'][^"']{8,}["']/gi, '$1=<REDACTED>')
+    .replace(/Authorization:\s*Bearer\s+\S{20,}/g, 'Authorization: Bearer <REDACTED>')
+    .replace(/process\.env\.[A-Z_]+\s*=\s*["'][^"']+["']/g, (match) => match.replace(/["'][^"']+["']/, '"<REDACTED>"'));
+}
+
+describe('System prompt invariance', () => {
+  test('exact system line matches regex', () => {
+    assert.match(buildSystemLine(), SYSTEM_LINE_REGEX);
+  });
+
+  test('rejects modified system prompt (no improvising)', () => {
+    const tampered = '[SYSTEM] You are Oracle, an improved problem solver with extra context.';
+    assert.doesNotMatch(tampered, SYSTEM_LINE_REGEX);
+  });
+
+  test('rejects empty system line', () => {
+    assert.doesNotMatch('[SYSTEM]', SYSTEM_LINE_REGEX);
+  });
+});
+
+describe('User section template', () => {
+  test('debug-source user line matches regex', () => {
+    const line = buildUserLine('debug', { cycles: 3, disproved: 'H1; H2; H3', error: '401 intermittent' });
+    assert.match(line, USER_LINE_REGEX);
+  });
+
+  test('fix-source user line matches regex', () => {
+    const line = buildUserLine('fix', {
+      attempts: 2,
+      file: 'src/auth.ts',
+      testFailure: 'expected 200, got 401',
+    });
+    assert.match(line, USER_LINE_REGEX);
+  });
+
+  test('rejects user line under 20 chars', () => {
+    assert.doesNotMatch('[USER] short', USER_LINE_REGEX);
+  });
+
+  test('manual mode accepts free-form within bounds', () => {
+    const line = `[USER] ${'x'.repeat(100)}`;
+    assert.match(line, USER_LINE_REGEX);
+  });
+});
+
+describe('File header structure', () => {
+  test('valid file header passes regex', () => {
+    assert.match('### File 1: src/auth/login.ts', FILE_HEADER_REGEX);
+    assert.match('### File 12: tests/e2e/checkout.spec.ts', FILE_HEADER_REGEX);
+  });
+
+  test('rejects malformed file headers', () => {
+    assert.doesNotMatch('### File: src/auth.ts', FILE_HEADER_REGEX);
+    assert.doesNotMatch('### file 1: src/auth.ts', FILE_HEADER_REGEX);
+    assert.doesNotMatch('## File 1: src/auth.ts', FILE_HEADER_REGEX);
+  });
+
+  test('files numbered sequentially from 1', () => {
+    const bundle = buildBundle({
+      systemLine: buildSystemLine(),
+      userLine: buildUserLine('manual', 'Why does the test fail intermittently?'),
+      files: [
+        { path: 'a.ts', content: 'a' },
+        { path: 'b.ts', content: 'b' },
+        { path: 'c.ts', content: 'c' },
+      ],
+    });
+    const result = validateBundle(bundle);
+    assert.strictEqual(result.valid, true, `unexpected errors: ${result.errors.join(', ')}`);
+  });
+});
+
+describe('Hard caps', () => {
+  test('rejects bundle with 13+ files', () => {
+    const files = Array.from({ length: 13 }, (_, i) => ({ path: `f${i}.ts`, content: 'x' }));
+    const bundle = buildBundle({ userLine: buildUserLine('manual', 'Why does this break under load?'), files });
+    const result = validateBundle(bundle);
+    assert.ok(result.errors.includes('too_many_files'));
+  });
+
+  test('accepts bundle with exactly 12 files', () => {
+    const files = Array.from({ length: 12 }, (_, i) => ({ path: `f${i}.ts`, content: 'x' }));
+    const bundle = buildBundle({ userLine: buildUserLine('manual', 'Why does this break under load?'), files });
+    const result = validateBundle(bundle);
+    assert.strictEqual(result.valid, true);
+  });
+
+  test('rejects bundle exceeding 400k chars total', () => {
+    const oversize = 'x'.repeat(50_000);
+    const files = Array.from({ length: 10 }, () => ({ path: 'big.ts', content: oversize }));
+    const bundle = buildBundle({ userLine: buildUserLine('manual', 'Why does this break under load?'), files });
+    const result = validateBundle(bundle);
+    assert.ok(result.errors.includes('bundle_too_large'));
+  });
+});
+
+describe('Secret redaction', () => {
+  test('redacts hardcoded api keys', () => {
+    const input = 'const apiKey = "sk-1234567890abcdef"';
+    const out = redactSecrets(input);
+    assert.match(out, /<REDACTED>/);
+    assert.doesNotMatch(out, /sk-1234567890abcdef/);
+  });
+
+  test('redacts Bearer tokens', () => {
+    const input = 'Authorization: Bearer abc123def456ghi789jkl000mno111';
+    const out = redactSecrets(input);
+    assert.match(out, /Bearer <REDACTED>/);
+  });
+
+  test('preserves non-secret content', () => {
+    const input = 'function login(user) { return user.id; }';
+    assert.strictEqual(redactSecrets(input), input);
+  });
+});
+
+describe('Signal naming compliance', () => {
+  const SIGNAL_PATTERN = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)+$/;
+
+  test('oracle.dispatched conforms to signal naming', () => {
+    assert.match('oracle.dispatched', SIGNAL_PATTERN);
+  });
+
+  test('oracle.response conforms to signal naming', () => {
+    assert.match('oracle.response', SIGNAL_PATTERN);
+  });
+
+  test('oracle.failed conforms to signal naming', () => {
+    assert.match('oracle.failed', SIGNAL_PATTERN);
+  });
+});