fix(ir): accept OpenAI role=developer at entry surface, normalize to system (#65)

* fix(ir): accept OpenAI role=developer at entry surface, normalize to system

Hermes Agent (v0.13+) and other modern openai-completions clients (Cline,
Continue.dev) default to role=developer for the high-priority instruction
slot when the model id matches OpenAI o1/o3+ reasoning family. OLP IR's
validator rejected this with 400 IR validation failed: role must be one
of system|user|assistant|tool, got "developer".

Reproduced 2026-05-27 on PI230 Hermes v0.14.0 trying olp-codex/gpt-5.5
through PI231 OLP. olp-claude (Anthropic models) was unaffected because
Hermes sends system role for Claude models (no developer-role concept
on Anthropic side).

Fix: extend openai-to-ir.mjs normalizeRole to map developer to system at
the entry boundary. The IR canonical-four-roles invariant is preserved;
every provider plugin's role-handling stays unchanged.

Same pattern as the existing function-to-tool normalization that already
lives in normalizeRole (function role was OpenAI-deprecated). Normalize-at-
entry centralizes role-spec-evolution handling in one file rather than
bloating the IR schema and forcing every provider plugin to handle each
new role.

Why not add developer to VALID_ROLES: it would require branches in three
provider plugins (anthropic, codex, mistral) all mapping to system-style
annotation anyway, plus wider IR surface for any future OpenAI role
addition.

Tests: two new pin tests in Suite IR translation:
- developer role to system translation
- mixed-role array including developer validates cleanly

768 to 770 tests, 0 fail. Verified Hermes via olp-codex no longer hits the
IR rejection error after this fix (smoke run from PI230).

ADR 0003 Amendment 3 documents the rationale + future-role policy
(normalize-at-entry unless a role genuinely conveys
provider-distinguishable semantics).

Authority: OpenAI Responses API spec developer-role + Hermes Agent
v0.14.0 reproduction.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* test+docs: PR #65 fold-in reviewer N2 + N3

N2 — Negative control test added: unknown role (e.g. "admin") still raises
BadRequestError. Pins that the developer-to-system normalization is the
only entry-surface escape hatch; any future widening of normalizeRole that
returns role as-is for unknown inputs will be caught by this test.

N3 — ADR 0003 Amendment 3 gains a "Cache-key impact" bullet documenting
that a developer-form and system-form request with otherwise-identical
content now share the same IR and thus the same cache key (per ADR 0005).
This is by design and matches OpenAI's own backward-compat semantics; the
note exists so a future debug session investigating "why does my developer
request hit a cache entry from an old system request" finds the answer.

Test count: 770 to 771, all pass.

Skipped reviewer N1 (URL precision) — Amendment already cites multiple
authorities including the Hermes/Cline tracking convention and live
reproduction transcript; single-URL precision is over-spec.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: dtzp555 <dtzp555@gmail.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

lib/ir/openai-to-ir.mjs

@@ -27,13 +27,28 @@ export class BadRequestError extends Error {
 // ── Role normalization ────────────────────────────────────────────────────
 
 /**
- * OpenAI deprecated role='function' in favour of role='tool'.
- * Per ADR 0003, IR supports system/user/assistant/tool.
+ * Normalize entry-surface role names → IR canonical set (system/user/assistant/tool).
+ *
+ * Per ADR 0003, IR supports exactly four roles. OpenAI's chat-completions
+ * spec has evolved beyond that, and we keep the IR minimal by normalizing
+ * at the entry boundary instead of bloating IR + every provider plugin.
+ *
+ * Current normalizations:
+ *   - `function` → `tool` — deprecated in OpenAI chat API, replaced by tool.
+ *   - `developer` → `system` — OpenAI o1/o3+ reasoning models accept a new
+ *     "developer" role with similar semantics to "system" (high-priority
+ *     instructions from the developer to the model). Providers like Hermes
+ *     Agent and Cline default to `developer` for openai-completions calls.
+ *     OLP-side anthropic + codex providers don't differentiate developer
+ *     from system, so the IR canonicalizes to `system` and downstream
+ *     translations remain unchanged.
+ *
  * @param {string} role
  * @returns {string}
  */
 function normalizeRole(role) {
   if (role === 'function') return 'tool';
+  if (role === 'developer') return 'system';
   return role;
 }