heyspex 0.1.0 → 0.2.0

package/spexharness/src/gates/id-display-format-gate.mjs

@@ -0,0 +1,190 @@
+// spexharness/src/gates/id-display-format-gate.mjs
+//
+// Engine port of scripts/claude-hooks/id-display-format-gate.mjs — the Stop
+// hook that catches a spec id written to the owner in the disallowed
+// parenthetical-annotation shape (`HS-OFUB-CVOB (epic, ...)` — neither
+// suffixed nor prose-prefixed, per communication-style-protocol.md). See
+// ./PORTING.md for the recipe this follows and ./env-vault-guard.mjs for the
+// reference port.
+//
+// This module does NOT reimplement the detection pattern (AC5's sibling
+// spirit — the pattern is registry-driven, not hand-coded here either). The
+// actual decision comes straight from the shared, already-pure loader:
+//   - scripts/claude-hooks/_guardrail-loader.mjs — loadGuardrails,
+//     rulesForSurface, isRuleEnabled, compilePatterns, proseOnly,
+//     matchContextAround. The `id-display-shape-gate` rule's regex lives in
+//     communication-style-protocol.md's `enforcement:` frontmatter, compiled
+//     into the registry by build-guardrails.mjs — this module only asks the
+//     loader to compile and apply it.
+//   - scripts/claude-hooks/_transcript-text.mjs — lastAssistantText, the same
+//     shared transcript-text reader naughty-list-gate.mjs's port also uses.
+// Both are dependency-free / no import hazard.
+//
+// JUDGMENT CALL — the original script does NOT export a pure decision
+// function; its logic is tangled inside main()'s stdin read. Per PORTING.md
+// step 1's "otherwise" branch this would normally move into the original
+// script itself, but this task's Do-nots forbid touching anything under
+// scripts/claude-hooks/. What is re-derived here is NOT the detection
+// pattern (that stays imported, per AC5's sibling spirit) — it is pure
+// string-formatting glue (`blockReason`, the warn-stderr message template)
+// copied verbatim from the original's own (unexported) helpers, plus the
+// interactive-rung resolver (`interactiveRung`, reading
+// HEYSPEX_ID_DISPLAY_GATE_INTERACTIVE) copied verbatim too — the identical
+// shape naughty-list-gate.mjs's port already uses for its own rung resolver.
+//
+// Event mapping: Stop → stop. `stdin.transcript_path` → `evt.transcriptPath`.
+//
+// Decision mapping — TWO rungs, the EXACT same shape as naughty-list-gate.mjs's
+// port (`warnOnly = !isAgent && interactiveRung(env) !== 'block'`, byte-for-
+// byte the original's own condition — read carefully, this gate's rung DOES
+// depend on CLAUDE_AGENT, same as its sibling; it is not the "warn regardless
+// of CLAUDE_AGENT" shape a first read of the header's "RUNG" note might
+// suggest — that note is about a *new gate class* starting warn-first, not
+// about ignoring CLAUDE_AGENT). CLAUDE_AGENT=true (or the rung explicitly
+// raised via HEYSPEX_ID_DISPLAY_GATE_INTERACTIVE=block) maps a hit to a real
+// `deny`; the interactive default (agent unset, rung not raised) maps the
+// SAME hit to a `rewrite` envelope (`{ warn: true, reason, hits }`) — the
+// stop is still allowed, matching the original's stderr-only warn path
+// exactly. This gives this gate natural coverage of allow (no hit), deny
+// (agent / raised rung), and rewrite (interactive default) for AC3.
+//
+// Not ported: the original's `appendGuardrailEvent(...)` audit-log write on
+// a hit — matching every other port in this set.
+//
+// Env hatches (unchanged):
+//   HEYSPEX_ID_DISPLAY_GATE_OFF=1               Hard kill switch.
+//   HEYSPEX_ID_DISPLAY_GATE_INTERACTIVE=block   Raise the rung to a real deny.
+// Also honors the rule's own registry configKey
+// (agent_behaviors.id_display_shape_gate.enabled) via isRuleEnabled.
+//
+// `ctx` contract (all optional; every field defaults to a real fs/env read):
+//   ctx.cwd  - repo root to resolve the guardrail registry from. Defaults to
+//              CLAUDE_PROJECT_DIR, else this repo's root. When given it is a
+//              self-contained fixture root and the rule's config toggle is read
+//              from it too.
+//   ctx.configRoot - the directory holding `.heyspex/config.yaml` (the rule's
+//              configKey toggle); wins over ctx.cwd for that read. With neither,
+//              the VAULT root (../config-root.mjs `defaultConfigRoot()`) — never
+//              CLAUDE_PROJECT_DIR, which under Claude Code is the app checkout,
+//              not where the settings file lives
+//              ([[HS-4C76-9W86-DIAG-heyspex-config-yaml-has-no-single-home]]).
+//   ctx.env  - env var overrides (tests use this instead of mutating
+//              process.env).
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { lastAssistantText } from '../../../scripts/claude-hooks/_transcript-text.mjs';
+import {
+  loadGuardrails,
+  rulesForSurface,
+  isRuleEnabled,
+  compilePatterns,
+  proseOnly,
+  matchContextAround,
+} from '../../../scripts/claude-hooks/_guardrail-loader.mjs';
+import { defaultConfigRoot } from '../config-root.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, '..', '..', '..');
+const RULE_ID = 'id-display-shape-gate';
+
+// Copied verbatim from the original's own (unexported) interactiveRung.
+function interactiveRung(env) {
+  const raw = String(env.HEYSPEX_ID_DISPLAY_GATE_INTERACTIVE ?? '').trim().toLowerCase();
+  return raw === 'block' ? 'block' : 'warn';
+}
+
+// Copied verbatim from the original's own (unexported) blockReason.
+function blockReason(hits) {
+  const lines = hits.map((h) => `  • "${h.excerpt}"`);
+  return (
+    `ID display violation: your last message wrote a spec id in a third shape — ` +
+    `neither suffixed (HS-OFUB-CVOB-EPIC) nor prose-prefixed (Epic: HS-OFUB-CVOB). ` +
+    `Rewrite using one of those two forms and resend:\n${lines.join('\n')}\n` +
+    `(Read the type off the spec's own type field, don't guess it. Break-glass: ` +
+    `HEYSPEX_ID_DISPLAY_GATE_OFF=1.)`
+  );
+}
+
+// Copied verbatim from the original's own (unexported) warn message template.
+function warnReason(hits) {
+  return (
+    `[id-display-format] warning — spec id written in a disallowed third shape (not blocked):\n` +
+    hits.map((h) => `  • "${h.excerpt}"`).join('\n') +
+    '\n'
+  );
+}
+
+/**
+ * The prose this stop event is about. A front that ALREADY holds the reply (`hs chat`, a
+ * headless seat, the bench — none of which write a Claude Code transcript file) passes it on
+ * the event as `text`, or on the ctx as `reply`; a Claude Code hook shell passes only
+ * `transcriptPath` and the text is read from it. Checked in that order, so the same gate runs
+ * on every front instead of silently allowing everything on the ones with no transcript --
+ * which is exactly what it did before (QC finding, 2026-09-10). The `ctx.reply` name matches
+ * enforce-session-sequence.mjs's stop-time corrector, which already took the reply that way.
+ *
+ * @param {{ text?: string, transcriptPath?: string }} evt
+ * @param {{ reply?: string }} ctx
+ * @param {(p: string) => string|null} readTranscript
+ * @returns {string}
+ */
+function stopEventText(evt, ctx, readTranscript) {
+  if (typeof ctx?.reply === 'string' && ctx.reply) return ctx.reply;
+  if (typeof evt?.text === 'string' && evt.text) return evt.text;
+  const transcriptPath = evt?.transcriptPath;
+  if (!transcriptPath) return '';
+  return readTranscript(transcriptPath) ?? '';
+}
+
+/** The id-display-format gate's id — unique across the built-in registry. */
+export const id = 'id-display-format-gate';
+/** Runs on the Stop event, same as its Stop Claude Code hook registration. */
+export const event = 'stop';
+/** Caller-defined severity label; this gate can deny (the raised rung), so it is "block". */
+export const severity = 'block';
+
+/**
+ * @param {{ point: string, text?: string, transcriptPath?: string }} evt
+ * @param {{ cwd?: string, configRoot?: string, reply?: string, env?: Record<string, string | undefined> }} [ctx]
+ * @returns {{ decision: 'allow'|'deny'|'rewrite', reason?: string, rewrite?: object }}
+ */
+export function run(evt, ctx = {}) {
+  const env = ctx.env ?? process.env;
+  if (String(env.HEYSPEX_ID_DISPLAY_GATE_OFF ?? '') === '1') {
+    return { decision: 'allow' };
+  }
+
+  const isAgent = env.CLAUDE_AGENT === 'true';
+  const warnOnly = !isAgent && interactiveRung(env) !== 'block';
+
+  const text = stopEventText(evt, ctx, lastAssistantText);
+  if (!text) return { decision: 'allow' };
+
+  const root = ctx.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? REPO_ROOT;
+  const configRoot = ctx.configRoot ?? (ctx.cwd ? ctx.cwd : defaultConfigRoot());
+  const guardrails = loadGuardrails(root);
+  const rule = rulesForSurface(guardrails, 'stop').find((r) => r.rule === RULE_ID);
+  if (!rule || !isRuleEnabled(rule, configRoot)) return { decision: 'allow' };
+
+  const patterns = compilePatterns(rule);
+  if (!patterns.length) return { decision: 'allow' };
+
+  const prose = proseOnly(text);
+  const hits = [];
+  for (const re of patterns) {
+    const m = re.exec(prose);
+    if (m) hits.push({ excerpt: matchContextAround(prose, m.index, m[0].length) });
+  }
+  if (!hits.length) return { decision: 'allow' };
+
+  if (!warnOnly) {
+    return { decision: 'deny', reason: blockReason(hits) };
+  }
+
+  const reason = warnReason(hits);
+  return { decision: 'rewrite', reason, rewrite: { warn: true, reason, hits } };
+}
+
+export default { id, event, severity, run };

package/spexharness/src/gates/inject-doctrine-gate.mjs

@@ -0,0 +1,89 @@
+// spexharness/src/gates/inject-doctrine-gate.mjs
+//
+// HS-X3S1 (DR3, epic [[HS-KNHZ-8CMW-EPIC-spexcode-doctrine-v0-the-foundational]]) — the
+// Claude Code plugin's SessionStart injection of the SpexCode Doctrine block, as a
+// registered engine gate (same architecture wave 6 of [[HS-AZ61-NYPR]] set: see
+// dev-server-awareness-gate.mjs's own header for the pattern this follows). Scope 3's own
+// words: "the SessionStart hook prints the same block (the plugin is a thin shell over the
+// same module)" — this module IS that same module (../doctrine/inject.mjs's `loadDoctrine`/
+// `renderDoctrineBlock`); scripts/claude-hooks/inject-doctrine.mjs is the thin shell
+// (`runGateAsHook(gate)`, exactly like inject-vault-context.mjs's own shell) that turns this
+// gate's decision into the Claude Code hook stdout contract. No new MCP tool — Scope 3 is
+// explicit that the block is context, never a tool.
+//
+// Registered under PORTED_GATES (gates/index.mjs) rather than a new top-level group: same
+// session_start point, same reserved band, same composition every front (registerAllGates)
+// already walks — a DeepSeek/local seat gets the Doctrine block through
+// session-bootstrap.mjs's own `doctrine` piece (this task's engine half), and a Claude Code
+// session gets the byte-identical block through THIS gate, so neither front can drift.
+//
+// Decision mapping: always `inject` (never allow-silently) — Scope 1/AC1's "absent (with a
+// notice) when the file is missing" applies here too: a repo with no Doctrine yet still
+// gets the absence-notice text, not nothing, so a Claude Code session is never silently
+// worse-informed than a DeepSeek seat's own bootstrap block would have been.
+//
+// Env hatch: HEYSPEX_DOCTRINE_OFF=1 (kill switch — no built-in rule-table wiring, like the
+// original per-hook `main()`-style scripts' own env-only kill switches).
+//
+// Audience (HS-A2PO, owner ruling 2026-10-03: "yes, inject-doctrine ships to customers.
+// Baseline foundational doctrine on which user's doctrine will be built ontop."): the hook
+// ships in the customer kit. ../doctrine/inject.mjs's resolveDoctrineSource picks the file —
+// the platform checkout (project root == package root) reads its learned
+// SPEXCODE-DOCTRINE.json exactly as before; a customer project reads ONLY the package's
+// baseline edition, and when that is missing or empty the gate allows silently (no absence
+// notice telling a customer to run a learner they never asked for).
+//
+// `ctx` contract (all optional; every field defaults to a real fs/env read):
+//   ctx.cwd          - project root of the session. Defaults to CLAUDE_PROJECT_DIR, then
+//                      CURSOR_PROJECT_DIR, then process.cwd().
+//   ctx.packageRoot  - the heyspex package root. Defaults to the root this module ships in.
+//   ctx.env          - env var overrides (tests use this instead of mutating process.env).
+
+import {
+  loadDoctrine,
+  renderDoctrineBlock,
+  DOCTRINE_MAX_TOKENS,
+  PACKAGE_ROOT,
+  resolveDoctrineSource,
+} from '../doctrine/inject.mjs';
+
+const OFF_ENV = 'HEYSPEX_DOCTRINE_OFF';
+
+/** The gate's id — unique across the registry. */
+export const id = 'inject-doctrine-gate';
+/** Runs at session start, same as its SessionStart Claude Code hook registration. */
+export const event = 'session_start';
+/** Caller-defined severity label; this gate only ever injects. */
+export const severity = 'info';
+
+/**
+ * @param {{ point: string, cwd?: string, agent?: string }} evt
+ * @param {{ cwd?: string, env?: Record<string, string|undefined> }} [ctx]
+ * @returns {{ decision: 'allow' }|{ decision: 'inject', reason: string,
+ *             inject: { additionalContext: string } }}
+ */
+export function run(evt, ctx = {}) {
+  const env = ctx.env ?? process.env;
+  if (String(env[OFF_ENV] ?? '') === '1') return { decision: 'allow' };
+
+  const projectRoot = ctx.cwd ?? env.CLAUDE_PROJECT_DIR ?? env.CURSOR_PROJECT_DIR ?? process.cwd();
+  const source = resolveDoctrineSource({ projectRoot, packageRoot: ctx.packageRoot ?? PACKAGE_ROOT });
+  let text;
+  try {
+    const doctrine = loadDoctrine({ path: source.path });
+    const hasPrinciples = Array.isArray(doctrine?.principles) && doctrine.principles.length > 0;
+    if (source.audience === 'customer' && !hasPrinciples) return { decision: 'allow' };
+    text = renderDoctrineBlock(doctrine, { maxTokens: DOCTRINE_MAX_TOKENS }).text;
+  } catch {
+    return { decision: 'allow' }; // fail-safe: a broken read never breaks session start
+  }
+  if (!text) return { decision: 'allow' };
+
+  return {
+    decision: 'inject',
+    reason: `${id}: SpexCode Doctrine block injected (${source.audience})`,
+    inject: { additionalContext: text },
+  };
+}
+
+export default { id, event, severity, run };

package/spexharness/src/gates/inject-vault-context.mjs

@@ -0,0 +1,239 @@
+// spexharness/src/gates/inject-vault-context.mjs
+//
+// Engine port of scripts/claude-hooks/inject-vault-context.mjs — the
+// UserPromptSubmit injection of VAULT SEARCH HITS
+// ([[HS-IAJE-2QX6-RES-grounding-agents-against-prior-decisions]],
+// [[HS-5KD3-LTGN-DIAG-prompt-submit-vault-grounding-never]]), wave 6 of
+// [[HS-AZ61-NYPR]]. The rule was Claude-Code-plugin-only, so a DeepSeek or
+// local seat started every prompt from scratch instead of from what the vault
+// had already decided. See ./PORTING.md for the recipe.
+//
+// This module does NOT reimplement the retrieval. Scoring, the prompt-shape
+// gate, the rarity weighting and the character cap all stay in
+// scripts/claude-hooks/_vault-retrieval.mjs — already a pure, shared library
+// with no stdin/stdout of its own — which this gate imports (PORTING.md step 1:
+// "if a pure decision function already exists, import it").
+//
+// P8 (HS-NRCK, plugin parity, epic [[HS-HEBV-8CMW-EPIC-spexcode-profile-v0-learn-the-developer]]):
+// this gate ALSO appends the SpexCode Profile block after its vault-context block, via
+// ../session-bootstrap.mjs's own `defaultProfileLoader` (P4's reader/renderer, never
+// reimplemented here) — so a Claude Code plugin session and a SpexCode seat's own
+// bootstrap see byte-identical profile content. Absence of the profile file (feature off,
+// or never learned) yields no section and no error, same as a fresh SpexCode seat.
+//
+// Event mapping: UserPromptSubmit → `prompt_submit` (../events.mjs).
+//
+// Decision mapping: the hook's only outcomes are "say nothing" and "emit
+// additionalContext". It NEVER rewrites the user's prompt (Claude Code has no
+// field for that, and the system preserves his words verbatim) and never
+// blocks. So: `allow` and `inject` — a PRIME injection, never a deny, which is
+// what this task's brief asks for in so many words.
+//
+// CONTEXT BUDGET ([[HS-1YDJ-NYPR-EPIC-context-budget-every-injection-measured]]).
+// Every byte this gate puts into a seat's window is measured through the ONE
+// measurement path (../context-budget.mjs's `recordContextInjection`, itself
+// built on ../token-inventory.mjs's `measurePiece`) and lands on the session
+// record as a `context_injection` event with `source: "inject-vault-context"` —
+// AC1 of that epic ("the session record shows bytes per injection with a
+// source"). Nothing here re-derives a byte count or writes its own inventory.
+//
+// The epic's AC2 ("under 500 bytes on a plain prompt") is satisfied by the
+// retrieval library's own prompt-shape gate, not by a new cap here: an ordinary
+// work order never reaches the index at all, so the recorded injection for a
+// plain prompt is ZERO bytes — nothing is recorded, because nothing is
+// injected. When the gate DOES fire, `_vault-retrieval.mjs`'s `MAX_CHARS` (600,
+// ~150 tokens) is the hard ceiling, enforced by dropping whole hits rather than
+// cutting a line mid-reference. `ctx.maxChars` can lower that for a front on a
+// tighter budget; it can never raise it above the library's own cap.
+//
+// Not ported HERE: nothing. The original hook writes no audit row (see
+// ../adapters/audit.mjs), so the pure decision is the whole of it.
+//
+// `ctx` contract (all optional; every field defaults to a real read):
+//   ctx.repoRoot      - the vault/app root the index is read from. Defaults to
+//                       the event's `cwd`, then CLAUDE_PROJECT_DIR, then this
+//                       repo's root. When given it is a self-contained fixture
+//                       root and the config toggle is read from it too.
+//   ctx.configRoot    - the directory holding `.heyspex/config.yaml` (the
+//                       TOGGLE_KEY read); wins over ctx.repoRoot for that read.
+//                       With neither, the VAULT root (../config-root.mjs
+//                       `defaultConfigRoot()`) — never the event's cwd or
+//                       CLAUDE_PROJECT_DIR, which under Claude Code is the app
+//                       checkout, not where the settings file lives
+//                       ([[HS-4C76-9W86-DIAG-heyspex-config-yaml-has-no-single-home]]).
+//   ctx.sessionRecord - a ../session-record.mjs record; when present the
+//                       injection is measured onto it.
+//   ctx.maxChars      - lower the emitted-character ceiling for this front.
+//   ctx.retrieve      - override the retrieval function (tests).
+//   ctx.env           - env var overrides (tests use this instead of mutating
+//                       process.env).
+//
+// Env hatch (unchanged): HEYSPEX_VAULT_CONTEXT_OFF=1.
+// Config toggle (unchanged): agent_behaviors.vault_context.enabled.
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { retrieveForPrompt, MAX_CHARS } from '../../../scripts/claude-hooks/_vault-retrieval.mjs';
+import { readConfigLeafRaw } from '../../../scripts/claude-hooks/_guardrail-loader.mjs';
+import { recordContextInjection } from '../context-budget.mjs';
+import { defaultProfileLoader } from '../session-bootstrap.mjs';
+import { defaultConfigRoot } from '../config-root.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, '..', '..', '..');
+
+const OFF_ENV = 'HEYSPEX_VAULT_CONTEXT_OFF';
+
+/** The `.heyspex/config.yaml` leaf that turns this injection off. */
+export const TOGGLE_KEY = 'agent_behaviors.vault_context.enabled';
+
+/** Trivially short prompts ("yes", "ok", "go ahead") carry nothing to retrieve on. */
+export const MIN_PROMPT_CHARS = 20;
+
+/** The `source` every measurement this gate records is stamped with. */
+export const INJECTION_SOURCE = 'inject-vault-context';
+
+/** The `source` the SpexCode Profile block (P8, HS-NRCK) is measured under — same
+ *  convention P4's own registerProfileContextUsage uses for a SpexCode seat's bootstrap. */
+export const PROFILE_INJECTION_SOURCE = 'spexcode-profile';
+
+/** This gate's id — unique across the registry. */
+export const id = 'inject-vault-context';
+/** Runs at prompt submit, same as its UserPromptSubmit hook registration. */
+export const event = 'prompt_submit';
+/** Caller-defined severity label; a prime injection, never a block. */
+export const severity = 'prime';
+
+/**
+ * The injected-content envelope guard: a prompt that is itself injected context
+ * from another gate must never be re-searched, or the block feeds on itself.
+ * Copied intact from the original hook.
+ */
+export function looksInjected(prompt) {
+  return /^(HEYSPEX|OWNER COMMUNICATION STYLE|VAULT CONTEXT)\b/.test(String(prompt ?? '').trim());
+}
+
+function resolveRoot(evt, ctx) {
+  if (typeof ctx.repoRoot === 'string' && ctx.repoRoot.trim()) {
+    return ctx.repoRoot.trim().replace(/[\\/]+$/, '');
+  }
+  if (typeof evt?.cwd === 'string' && evt.cwd.trim()) return evt.cwd.trim().replace(/[\\/]+$/, '');
+  const env = ctx.env ?? process.env;
+  const fromEnv = env.CLAUDE_PROJECT_DIR?.trim();
+  if (fromEnv) return fromEnv.replace(/[\\/]+$/, '');
+  return REPO_ROOT;
+}
+
+/**
+ * @param {{ point: string, prompt?: string, cwd?: string }} evt
+ * @param {{ repoRoot?: string, configRoot?: string, sessionRecord?: object, maxChars?: number,
+ *   retrieve?: (prompt: string, root: string, options: object) => (string|null),
+ *   env?: Record<string, string | undefined> }} [ctx]
+ * @returns {{ decision: 'allow'|'inject',
+ *   inject?: { additionalContext: string, severity: string },
+ *   measurement?: { source: string, name: string, tokens: number, chars: number } }}
+ */
+export function run(evt, ctx = {}) {
+  const env = ctx.env ?? process.env;
+  if (String(env[OFF_ENV] ?? '') === '1') return { decision: 'allow' };
+
+  const root = resolveRoot(evt, ctx);
+  // Only a ctx-supplied root is a fixture; the event's cwd / CLAUDE_PROJECT_DIR are the live
+  // app checkout and never decide where the settings file is read from.
+  const fixtureRoot = typeof ctx.repoRoot === 'string' && ctx.repoRoot.trim();
+  const configRoot = ctx.configRoot ?? (fixtureRoot ? root : defaultConfigRoot());
+
+  // ── vault-context retrieval (unchanged decision logic) ──────────────────────────
+  // Config toggle, default ON when the key is absent (same semantics as the hook).
+  const vaultContextEnabled = !(() => {
+    const enabled = readConfigLeafRaw(TOGGLE_KEY, configRoot);
+    return enabled === 'false' || enabled === false;
+  })();
+
+  let vaultBlock = null;
+  if (vaultContextEnabled) {
+    const prompt = evt?.prompt;
+    if (typeof prompt === 'string' && prompt.trim().length >= MIN_PROMPT_CHARS && !looksInjected(prompt)) {
+      const maxChars = Number.isFinite(ctx.maxChars)
+        ? Math.min(Number(ctx.maxChars), MAX_CHARS)
+        : MAX_CHARS;
+      const retrieve = ctx.retrieve ?? retrieveForPrompt;
+      try {
+        vaultBlock = retrieve(prompt, root, { maxChars });
+      } catch {
+        // A crashed retrieval injects nothing — never the reason a turn breaks.
+        vaultBlock = null;
+      }
+    }
+  }
+
+  // The ONE measurement path (HS-7UAQ / epic HS-1YDJ). A front with no session
+  // record still gets the bytes back on the decision; nothing measures twice.
+  const vaultMeasurement = vaultBlock
+    ? ctx.sessionRecord
+      ? recordContextInjection(ctx.sessionRecord, {
+          source: INJECTION_SOURCE,
+          name: 'vault-context',
+          text: vaultBlock,
+        })
+      : {
+          source: INJECTION_SOURCE,
+          name: 'vault-context',
+          chars: vaultBlock.length,
+          tokens: Math.ceil(vaultBlock.length / 4),
+          estimated: true,
+        }
+    : null;
+
+  // ── SpexCode Profile parity (P8, HS-NRCK) ────────────────────────────────────────
+  // Thin shell over session-bootstrap.mjs's own `defaultProfileLoader` (P4) — the SAME
+  // reader/renderer every SpexCode seat's bootstrap uses; never a second rendering
+  // implementation. Absence of the profile file (feature off, or never learned) yields
+  // `null` here, same as it does for a fresh SpexCode seat — no section, no error (AC2).
+  // Positioned AFTER the vault-context block: Doctrine itself already rode in earlier, at
+  // SessionStart, via its own hook (inject-doctrine.mjs/inject-doctrine-gate.mjs), so the
+  // developer-visible order across a session stays enforced -> learned Doctrine ->
+  // per-developer Profile exactly as session-bootstrap.mjs's BOOTSTRAP_PIECES documents.
+  let profile = null;
+  try {
+    profile = defaultProfileLoader({ root });
+  } catch {
+    // A broken profile read never breaks the turn — same fail-soft posture as retrieval.
+    profile = null;
+  }
+  const profileBlock = profile && typeof profile.text === 'string' && profile.text.trim() ? profile.text : null;
+
+  const profileMeasurement = profileBlock
+    ? ctx.sessionRecord
+      ? recordContextInjection(ctx.sessionRecord, {
+          source: PROFILE_INJECTION_SOURCE,
+          name: 'spexcode-profile',
+          text: profileBlock,
+          tokens: profile.tokens,
+        })
+      : {
+          source: PROFILE_INJECTION_SOURCE,
+          name: 'spexcode-profile',
+          chars: profile.chars,
+          tokens: profile.tokens,
+          estimated: true,
+        }
+    : null;
+
+  if (!vaultBlock && !profileBlock) return { decision: 'allow' };
+
+  const additionalContext = [vaultBlock, profileBlock].filter(Boolean).join('\n\n');
+  const measurements = [vaultMeasurement, profileMeasurement].filter(Boolean);
+
+  return {
+    decision: 'inject',
+    inject: { additionalContext, severity: 'prime' },
+    // Single measurement, unchanged shape, when only one piece fired (the common case and
+    // every pre-existing caller's expectation); an array only when both fired in the same
+    // turn.
+    measurement: measurements.length <= 1 ? measurements[0] ?? null : measurements,
+  };
+}
+
+export default { id, event, severity, run };