@praxisflux/gates 0.62.0 → 0.63.1

package/codebase-to-course/lib/README.md

@@ -7,6 +7,10 @@ Planned modules (**TASK-1.2**): `project-root` · `gate-runner` (Stop-hook harne
 · `selfcontained` (HTML verifier) · `lifecycle` (status-cannot-exceed-proven-artifacts) ·
 `installer` · `dates` · `template`.
 
+Also shipped: `structured-offload` — schema-validated, fail-soft calls to a local
+Ollama/OpenAI-compatible endpoint, config-driven (`.claude/structured-offload.json`),
+opt-in and absent-by-default. See `docs/wiki/chassis.md`.
+
 Also shipped here: `handoff-protocol.md` — a stamped copy of the canonical
 `docs/handoff-protocol.md` (re-stamped by `scripts/sync-shared.mjs`), so skills can reference
 the protocol as `${CLAUDE_PLUGIN_ROOT}/lib/handoff-protocol.md` from an installed plugin.

package/codebase-to-course/lib/board-mirror.mjs

@@ -264,12 +264,23 @@ export function isPausedLink(link) {
  * Indexes are POSITIONAL (1-based) within the block — a position, not an identity. A reordered
  * block renumbers.
  *
- * `parseSpecPhasesBlock` tolerates two normalizations a live Jira write→read round-trip is known
- * to introduce on EVERY read (same findings file): a blank line inserted immediately after
- * BEGIN (skipped here — a blank line is never a checkbox line) and two trailing spaces appended
+ * `parseSpecPhasesBlock` tolerates THREE normalizations a live Jira write→read round-trip is
+ * known to introduce on EVERY read (same findings file): a blank line inserted immediately after
+ * BEGIN (skipped here — a blank line is never a checkbox line), two trailing spaces appended
  * to the LAST checkbox line (needs no extra handling: TASK_LINE's own `(\S.*?)\s*$` already
- * strips trailing whitespace from the captured text). Reuses TASK_LINE from spec-derive.mjs
- * rather than a third checkbox regex. */
+ * strips trailing whitespace from the captured text), and two trailing spaces appended to the
+ * END MARKER LINE itself (verified live 2026-09-10, spec 056 phase 2 — the slice on
+ * indexOf(END) leaves them outside every item, so they never reach the parse). Reuses TASK_LINE
+ * from spec-derive.mjs rather than a third checkbox regex.
+ *
+ * WHY THE RENDERER RIGHT-TRIMS (spec 056 phase 3, verified live): that END-marker whitespace
+ * COMPOUNDS if echoed back. Read 2 spaces, write them back unchanged, and the next read returns
+ * 4 — then 6, and so on, because Jira appends its own on top of whatever it is given. Phase 1
+ * recorded the cycle as "idempotent, not degrading", which held for the checkbox lines it
+ * measured but NOT for the END marker. `renderSpecPhasesBlock` emits a clean marker with no
+ * trailing whitespace, which re-normalizes every cycle back to a constant 2 (confirmed by a
+ * live write of a clean marker returning exactly 2). Splice the rendered block between the
+ * existing markers rather than preserving the read bytes, and the growth cannot start. */
 
 const SPEC_PHASES_BEGIN = "<!-- spec-phases BEGIN -->";
 const SPEC_PHASES_END = "<!-- spec-phases END -->";
@@ -402,6 +413,12 @@ export function projectBacklog(root) {
  *  `jira` by adding one key here; no `if (provider === "...")` branch belongs anywhere. */
 export const providers = {
   backlog: { requiresSync: false, project: projectBacklog },
+  // spec 056 R1. `project: null` is not an omission — it is the TYPE-LEVEL statement that this
+  // provider cannot be projected by `node` alone (it needs MCP, hence a skill). Registering it
+  // is what activates spec 052 R5's `--check` behavior and spec 053 R3/R4's staleness and
+  // missing-mirror findings for a Jira host. No `if (provider === "jira")` branch belongs
+  // anywhere: the shape of this entry carries the distinction.
+  jira: { requiresSync: true, project: null },
 };
 
 /* ── `.board.json` config schema (spec 054) — a SEPARATE, smaller table from `providers`
@@ -462,10 +479,65 @@ export function validateBoardConfig(config) {
       if (!sub[field]) problems.push(`${name}.${field}: required for provider "${name}"`);
     if (sub.statusMap !== undefined && (typeof sub.statusMap !== "object" || Array.isArray(sub.statusMap) || sub.statusMap === null))
       problems.push(`${name}.statusMap: expected object, got ${Array.isArray(sub.statusMap) ? "array" : typeof sub.statusMap}`);
+    if (sub.statusReadMap !== undefined && (typeof sub.statusReadMap !== "object" || Array.isArray(sub.statusReadMap) || sub.statusReadMap === null))
+      problems.push(`${name}.statusReadMap: expected object, got ${Array.isArray(sub.statusReadMap) ? "array" : typeof sub.statusReadMap}`);
+    // The injectivity rule differs BY DIRECTION and that asymmetry is the whole point (spec 056
+    // Phase 2 / the 2026-09-10 operator ruling). `statusMap` is bridge -> site: it names the one
+    // canonical WRITE target per bridge status, so two bridge statuses sharing a site status
+    // makes the reverse read ambiguous and is an ERROR. `statusReadMap` is site -> bridge and is
+    // many-to-one BY DESIGN (a 15-status workflow collapsing onto 3), so it is deliberately
+    // exempt. Silently picking a winner would make verdicts depend on key order.
+    if (sub.statusMap && typeof sub.statusMap === "object" && !Array.isArray(sub.statusMap)) {
+      const seen = new Map();
+      for (const [bridge, site] of Object.entries(sub.statusMap)) {
+        if (typeof site !== "string") continue;
+        const prior = seen.get(site);
+        if (prior !== undefined)
+          problems.push(`${name}.statusMap: non-injective — "${prior}" and "${bridge}" both map to site status "${site}"; the reverse read would be ambiguous`);
+        else seen.set(site, bridge);
+      }
+    }
   }
   return problems;
 }
 
+/* ── status mapping, both directions (spec 054 R1 + spec 056 Phase 2's ratified amendment) ──
+ *
+ * Two fields, because the two directions have genuinely different shapes and one field cannot
+ * honestly carry both:
+ *
+ *   bridge status ──statusMap──▶ site status      (WRITE: injective, one canonical target)
+ *   site status ──statusReadMap──▶ bridge status  (READ: many-to-one BY DESIGN)
+ *
+ * The live workflow that forced this had FIFTEEN statuses against the bridge's three
+ * (`bridge.mjs`'s RANK: to do / in progress / done). Collapsing 15 onto 3 is inherently
+ * many-to-one, while the write direction must pick exactly one target per bridge status.
+ * See specs/056-jira-provider/findings/phase-2-operator-rulings.md, ruling 2.
+ *
+ * Both directions FALL THROUGH UNCHANGED on a miss — spec 054 R1's stated rule, kept here so a
+ * host with no map at all behaves exactly as it did before either field existed. */
+
+/** Map a bridge status to the site's workflow status for a WRITE. Falls through unchanged. */
+export function toSiteStatus(bridgeStatus, config = {}) {
+  return config?.statusMap?.[bridgeStatus] ?? bridgeStatus;
+}
+
+/** Map a site workflow status back to the bridge's vocabulary for a READ. Prefers the explicit
+ *  many-to-one `statusReadMap`; with none, inverts `statusMap` (so a host that predates
+ *  `statusReadMap` keeps its exact prior behavior). Falls through unchanged on a miss — the
+ *  caller's `verdict()` then reports "unknown" for a status outside the vocabulary rather than
+ *  this function guessing one. */
+export function toBridgeStatus(siteStatus, config = {}) {
+  const read = config?.statusReadMap;
+  if (read && typeof read === "object" && !Array.isArray(read) && read[siteStatus] !== undefined)
+    return read[siteStatus];
+  const write = config?.statusMap;
+  if (write && typeof write === "object" && !Array.isArray(write)) {
+    for (const [bridge, site] of Object.entries(write)) if (site === siteStatus) return bridge;
+  }
+  return siteStatus;
+}
+
 /** Run git argv `args` in `cwd`. Never throws — a git failure is data, not an exception,
  *  matching grounding-wiki/gates/repin-window.mjs's `git()` helper shape (spawnSync, argv
  *  array so there is no shell, utf8 encoding). Returns `{ status, out }`; `status` is `null`

package/codebase-to-course/lib/structured-offload.mjs

@@ -0,0 +1,140 @@
+// structured-offload.mjs — schema-validated calls to a local model, fail-soft always.
+//
+// `offload({ prompt, schema, config, timeoutMs })` asks a local Ollama or
+// OpenAI-compatible endpoint to answer `prompt`, constrained to `schema` at the backend
+// (Ollama `format`, OpenAI-compatible `response_format: json_schema`) so the model is
+// structurally prevented from returning prose. The result is validated again on this
+// side against the same schema. NEVER throws: every failure path — unset config,
+// timeout, connection refused, non-2xx, invalid JSON, schema mismatch — resolves to
+// `{ ok: false, reason, residue }` and the caller does the work in-session, exactly as
+// if this module did not exist.
+//
+// `config` is loaded by `loadConfig(root)` from `<root>/.claude/structured-offload.json`
+// (absent/unreadable/malformed -> null -> `reason: 'unconfigured'`), kept separate from
+// `offload` so tests can hand it a stub-server config directly without touching disk.
+//
+// Config shape: `{ endpoint, api: 'ollama'|'openai', model, timeoutMs?, residuePath? }`.
+//
+// Schema checker (minimal subset — extend only when a consumer needs more):
+//   - `type`: 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean'
+//   - `required`: array of property names that must exist on an object value
+//   - `properties`: per-key sub-schemas, checked recursively
+//   - `enum`: value must be one of the listed members
+//   - `items`: sub-schema every array element must satisfy
+// ponytail: full JSON Schema (oneOf/anyOf/patternProperties/formats/…) is not
+// implemented; the checked subset is what closed-enum/path-lookup callers need.
+//
+// `residue`: `{ backend, model, outcome: 'validated'|'fallback', reason?, ms }`,
+// returned on every call and appended as a JSON line to `config.residuePath` when set.
+
+import { readFileSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Load and validate the config file, or null on any absence/parse/shape failure. */
+export function loadConfig(root) {
+  try {
+    const cfg = JSON.parse(readFileSync(join(root, ".claude", "structured-offload.json"), "utf8"));
+    if (!cfg || typeof cfg !== "object") return null;
+    if (!cfg.endpoint || !["ollama", "openai"].includes(cfg.api) || !cfg.model) return null;
+    return cfg;
+  } catch {
+    return null;
+  }
+}
+
+function isTimeoutError(err) {
+  return err?.name === "TimeoutError" || err?.name === "AbortError";
+}
+
+function buildRequest(config, prompt, schema) {
+  const messages = [{ role: "user", content: prompt }];
+  if (config.api === "ollama") {
+    return { path: "/api/chat", body: { model: config.model, messages, format: schema, stream: false } };
+  }
+  return {
+    path: "/v1/chat/completions",
+    body: {
+      model: config.model,
+      messages,
+      response_format: { type: "json_schema", json_schema: { name: "offload_response", strict: true, schema } },
+    },
+  };
+}
+
+function extractContent(api, data) {
+  return api === "ollama" ? data?.message?.content : data?.choices?.[0]?.message?.content;
+}
+
+/** The minimal schema subset documented in the module header. */
+export function validateSchema(value, schema) {
+  if (!schema) return true;
+  if (schema.enum) return schema.enum.includes(value);
+  switch (schema.type) {
+    case "object": {
+      if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+      for (const key of schema.required || []) if (!(key in value)) return false;
+      if (schema.properties) {
+        for (const [key, sub] of Object.entries(schema.properties)) {
+          if (key in value && !validateSchema(value[key], sub)) return false;
+        }
+      }
+      return true;
+    }
+    case "array":
+      return Array.isArray(value) && (!schema.items || value.every((v) => validateSchema(v, schema.items)));
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number";
+    case "integer":
+      return Number.isInteger(value);
+    case "boolean":
+      return typeof value === "boolean";
+    default:
+      return true;
+  }
+}
+
+/** Async, never-throwing: see module header for the full contract. */
+export async function offload({ prompt, schema, config, timeoutMs } = {}) {
+  const start = Date.now();
+  const backend = config?.api;
+  const model = config?.model;
+
+  function finish(result) {
+    const residue = { backend, model, outcome: result.ok ? "validated" : "fallback", ms: Date.now() - start };
+    if (!result.ok) residue.reason = result.reason;
+    if (config?.residuePath) {
+      try { appendFileSync(config.residuePath, JSON.stringify(residue) + "\n"); } catch { /* residue is best-effort */ }
+    }
+    return { ...result, residue };
+  }
+  const fail = (reason) => finish({ ok: false, reason });
+
+  if (!config || !config.endpoint || !["ollama", "openai"].includes(config.api) || !config.model) {
+    return fail("unconfigured");
+  }
+
+  const { path, body } = buildRequest(config, prompt, schema);
+  let res;
+  try {
+    res = await fetch(new URL(path, config.endpoint), {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs ?? config.timeoutMs ?? 30000),
+    });
+  } catch (err) {
+    return fail(isTimeoutError(err) ? "timeout" : "refused");
+  }
+  if (!res.ok) return fail("http-error");
+
+  let data;
+  try { data = await res.json(); } catch { return fail("invalid-json"); }
+
+  let value;
+  try { value = JSON.parse(extractContent(config.api, data)); } catch { return fail("invalid-json"); }
+
+  if (!validateSchema(value, schema)) return fail("schema-mismatch");
+  return finish({ ok: true, value });
+}

package/grounding-wiki/lib/README.md

@@ -7,6 +7,10 @@ Planned modules (**TASK-1.2**): `project-root` · `gate-runner` (Stop-hook harne
 · `selfcontained` (HTML verifier) · `lifecycle` (status-cannot-exceed-proven-artifacts) ·
 `installer` · `dates` · `template`.
 
+Also shipped: `structured-offload` — schema-validated, fail-soft calls to a local
+Ollama/OpenAI-compatible endpoint, config-driven (`.claude/structured-offload.json`),
+opt-in and absent-by-default. See `docs/wiki/chassis.md`.
+
 Also shipped here: `handoff-protocol.md` — a stamped copy of the canonical
 `docs/handoff-protocol.md` (re-stamped by `scripts/sync-shared.mjs`), so skills can reference
 the protocol as `${CLAUDE_PLUGIN_ROOT}/lib/handoff-protocol.md` from an installed plugin.

package/grounding-wiki/lib/board-mirror.mjs

@@ -264,12 +264,23 @@ export function isPausedLink(link) {
  * Indexes are POSITIONAL (1-based) within the block — a position, not an identity. A reordered
  * block renumbers.
  *
- * `parseSpecPhasesBlock` tolerates two normalizations a live Jira write→read round-trip is known
- * to introduce on EVERY read (same findings file): a blank line inserted immediately after
- * BEGIN (skipped here — a blank line is never a checkbox line) and two trailing spaces appended
+ * `parseSpecPhasesBlock` tolerates THREE normalizations a live Jira write→read round-trip is
+ * known to introduce on EVERY read (same findings file): a blank line inserted immediately after
+ * BEGIN (skipped here — a blank line is never a checkbox line), two trailing spaces appended
  * to the LAST checkbox line (needs no extra handling: TASK_LINE's own `(\S.*?)\s*$` already
- * strips trailing whitespace from the captured text). Reuses TASK_LINE from spec-derive.mjs
- * rather than a third checkbox regex. */
+ * strips trailing whitespace from the captured text), and two trailing spaces appended to the
+ * END MARKER LINE itself (verified live 2026-09-10, spec 056 phase 2 — the slice on
+ * indexOf(END) leaves them outside every item, so they never reach the parse). Reuses TASK_LINE
+ * from spec-derive.mjs rather than a third checkbox regex.
+ *
+ * WHY THE RENDERER RIGHT-TRIMS (spec 056 phase 3, verified live): that END-marker whitespace
+ * COMPOUNDS if echoed back. Read 2 spaces, write them back unchanged, and the next read returns
+ * 4 — then 6, and so on, because Jira appends its own on top of whatever it is given. Phase 1
+ * recorded the cycle as "idempotent, not degrading", which held for the checkbox lines it
+ * measured but NOT for the END marker. `renderSpecPhasesBlock` emits a clean marker with no
+ * trailing whitespace, which re-normalizes every cycle back to a constant 2 (confirmed by a
+ * live write of a clean marker returning exactly 2). Splice the rendered block between the
+ * existing markers rather than preserving the read bytes, and the growth cannot start. */
 
 const SPEC_PHASES_BEGIN = "<!-- spec-phases BEGIN -->";
 const SPEC_PHASES_END = "<!-- spec-phases END -->";
@@ -402,6 +413,12 @@ export function projectBacklog(root) {
  *  `jira` by adding one key here; no `if (provider === "...")` branch belongs anywhere. */
 export const providers = {
   backlog: { requiresSync: false, project: projectBacklog },
+  // spec 056 R1. `project: null` is not an omission — it is the TYPE-LEVEL statement that this
+  // provider cannot be projected by `node` alone (it needs MCP, hence a skill). Registering it
+  // is what activates spec 052 R5's `--check` behavior and spec 053 R3/R4's staleness and
+  // missing-mirror findings for a Jira host. No `if (provider === "jira")` branch belongs
+  // anywhere: the shape of this entry carries the distinction.
+  jira: { requiresSync: true, project: null },
 };
 
 /* ── `.board.json` config schema (spec 054) — a SEPARATE, smaller table from `providers`
@@ -462,10 +479,65 @@ export function validateBoardConfig(config) {
       if (!sub[field]) problems.push(`${name}.${field}: required for provider "${name}"`);
     if (sub.statusMap !== undefined && (typeof sub.statusMap !== "object" || Array.isArray(sub.statusMap) || sub.statusMap === null))
       problems.push(`${name}.statusMap: expected object, got ${Array.isArray(sub.statusMap) ? "array" : typeof sub.statusMap}`);
+    if (sub.statusReadMap !== undefined && (typeof sub.statusReadMap !== "object" || Array.isArray(sub.statusReadMap) || sub.statusReadMap === null))
+      problems.push(`${name}.statusReadMap: expected object, got ${Array.isArray(sub.statusReadMap) ? "array" : typeof sub.statusReadMap}`);
+    // The injectivity rule differs BY DIRECTION and that asymmetry is the whole point (spec 056
+    // Phase 2 / the 2026-09-10 operator ruling). `statusMap` is bridge -> site: it names the one
+    // canonical WRITE target per bridge status, so two bridge statuses sharing a site status
+    // makes the reverse read ambiguous and is an ERROR. `statusReadMap` is site -> bridge and is
+    // many-to-one BY DESIGN (a 15-status workflow collapsing onto 3), so it is deliberately
+    // exempt. Silently picking a winner would make verdicts depend on key order.
+    if (sub.statusMap && typeof sub.statusMap === "object" && !Array.isArray(sub.statusMap)) {
+      const seen = new Map();
+      for (const [bridge, site] of Object.entries(sub.statusMap)) {
+        if (typeof site !== "string") continue;
+        const prior = seen.get(site);
+        if (prior !== undefined)
+          problems.push(`${name}.statusMap: non-injective — "${prior}" and "${bridge}" both map to site status "${site}"; the reverse read would be ambiguous`);
+        else seen.set(site, bridge);
+      }
+    }
   }
   return problems;
 }
 
+/* ── status mapping, both directions (spec 054 R1 + spec 056 Phase 2's ratified amendment) ──
+ *
+ * Two fields, because the two directions have genuinely different shapes and one field cannot
+ * honestly carry both:
+ *
+ *   bridge status ──statusMap──▶ site status      (WRITE: injective, one canonical target)
+ *   site status ──statusReadMap──▶ bridge status  (READ: many-to-one BY DESIGN)
+ *
+ * The live workflow that forced this had FIFTEEN statuses against the bridge's three
+ * (`bridge.mjs`'s RANK: to do / in progress / done). Collapsing 15 onto 3 is inherently
+ * many-to-one, while the write direction must pick exactly one target per bridge status.
+ * See specs/056-jira-provider/findings/phase-2-operator-rulings.md, ruling 2.
+ *
+ * Both directions FALL THROUGH UNCHANGED on a miss — spec 054 R1's stated rule, kept here so a
+ * host with no map at all behaves exactly as it did before either field existed. */
+
+/** Map a bridge status to the site's workflow status for a WRITE. Falls through unchanged. */
+export function toSiteStatus(bridgeStatus, config = {}) {
+  return config?.statusMap?.[bridgeStatus] ?? bridgeStatus;
+}
+
+/** Map a site workflow status back to the bridge's vocabulary for a READ. Prefers the explicit
+ *  many-to-one `statusReadMap`; with none, inverts `statusMap` (so a host that predates
+ *  `statusReadMap` keeps its exact prior behavior). Falls through unchanged on a miss — the
+ *  caller's `verdict()` then reports "unknown" for a status outside the vocabulary rather than
+ *  this function guessing one. */
+export function toBridgeStatus(siteStatus, config = {}) {
+  const read = config?.statusReadMap;
+  if (read && typeof read === "object" && !Array.isArray(read) && read[siteStatus] !== undefined)
+    return read[siteStatus];
+  const write = config?.statusMap;
+  if (write && typeof write === "object" && !Array.isArray(write)) {
+    for (const [bridge, site] of Object.entries(write)) if (site === siteStatus) return bridge;
+  }
+  return siteStatus;
+}
+
 /** Run git argv `args` in `cwd`. Never throws — a git failure is data, not an exception,
  *  matching grounding-wiki/gates/repin-window.mjs's `git()` helper shape (spawnSync, argv
  *  array so there is no shell, utf8 encoding). Returns `{ status, out }`; `status` is `null`

package/grounding-wiki/lib/structured-offload.mjs

@@ -0,0 +1,140 @@
+// structured-offload.mjs — schema-validated calls to a local model, fail-soft always.
+//
+// `offload({ prompt, schema, config, timeoutMs })` asks a local Ollama or
+// OpenAI-compatible endpoint to answer `prompt`, constrained to `schema` at the backend
+// (Ollama `format`, OpenAI-compatible `response_format: json_schema`) so the model is
+// structurally prevented from returning prose. The result is validated again on this
+// side against the same schema. NEVER throws: every failure path — unset config,
+// timeout, connection refused, non-2xx, invalid JSON, schema mismatch — resolves to
+// `{ ok: false, reason, residue }` and the caller does the work in-session, exactly as
+// if this module did not exist.
+//
+// `config` is loaded by `loadConfig(root)` from `<root>/.claude/structured-offload.json`
+// (absent/unreadable/malformed -> null -> `reason: 'unconfigured'`), kept separate from
+// `offload` so tests can hand it a stub-server config directly without touching disk.
+//
+// Config shape: `{ endpoint, api: 'ollama'|'openai', model, timeoutMs?, residuePath? }`.
+//
+// Schema checker (minimal subset — extend only when a consumer needs more):
+//   - `type`: 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean'
+//   - `required`: array of property names that must exist on an object value
+//   - `properties`: per-key sub-schemas, checked recursively
+//   - `enum`: value must be one of the listed members
+//   - `items`: sub-schema every array element must satisfy
+// ponytail: full JSON Schema (oneOf/anyOf/patternProperties/formats/…) is not
+// implemented; the checked subset is what closed-enum/path-lookup callers need.
+//
+// `residue`: `{ backend, model, outcome: 'validated'|'fallback', reason?, ms }`,
+// returned on every call and appended as a JSON line to `config.residuePath` when set.
+
+import { readFileSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Load and validate the config file, or null on any absence/parse/shape failure. */
+export function loadConfig(root) {
+  try {
+    const cfg = JSON.parse(readFileSync(join(root, ".claude", "structured-offload.json"), "utf8"));
+    if (!cfg || typeof cfg !== "object") return null;
+    if (!cfg.endpoint || !["ollama", "openai"].includes(cfg.api) || !cfg.model) return null;
+    return cfg;
+  } catch {
+    return null;
+  }
+}
+
+function isTimeoutError(err) {
+  return err?.name === "TimeoutError" || err?.name === "AbortError";
+}
+
+function buildRequest(config, prompt, schema) {
+  const messages = [{ role: "user", content: prompt }];
+  if (config.api === "ollama") {
+    return { path: "/api/chat", body: { model: config.model, messages, format: schema, stream: false } };
+  }
+  return {
+    path: "/v1/chat/completions",
+    body: {
+      model: config.model,
+      messages,
+      response_format: { type: "json_schema", json_schema: { name: "offload_response", strict: true, schema } },
+    },
+  };
+}
+
+function extractContent(api, data) {
+  return api === "ollama" ? data?.message?.content : data?.choices?.[0]?.message?.content;
+}
+
+/** The minimal schema subset documented in the module header. */
+export function validateSchema(value, schema) {
+  if (!schema) return true;
+  if (schema.enum) return schema.enum.includes(value);
+  switch (schema.type) {
+    case "object": {
+      if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+      for (const key of schema.required || []) if (!(key in value)) return false;
+      if (schema.properties) {
+        for (const [key, sub] of Object.entries(schema.properties)) {
+          if (key in value && !validateSchema(value[key], sub)) return false;
+        }
+      }
+      return true;
+    }
+    case "array":
+      return Array.isArray(value) && (!schema.items || value.every((v) => validateSchema(v, schema.items)));
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number";
+    case "integer":
+      return Number.isInteger(value);
+    case "boolean":
+      return typeof value === "boolean";
+    default:
+      return true;
+  }
+}
+
+/** Async, never-throwing: see module header for the full contract. */
+export async function offload({ prompt, schema, config, timeoutMs } = {}) {
+  const start = Date.now();
+  const backend = config?.api;
+  const model = config?.model;
+
+  function finish(result) {
+    const residue = { backend, model, outcome: result.ok ? "validated" : "fallback", ms: Date.now() - start };
+    if (!result.ok) residue.reason = result.reason;
+    if (config?.residuePath) {
+      try { appendFileSync(config.residuePath, JSON.stringify(residue) + "\n"); } catch { /* residue is best-effort */ }
+    }
+    return { ...result, residue };
+  }
+  const fail = (reason) => finish({ ok: false, reason });
+
+  if (!config || !config.endpoint || !["ollama", "openai"].includes(config.api) || !config.model) {
+    return fail("unconfigured");
+  }
+
+  const { path, body } = buildRequest(config, prompt, schema);
+  let res;
+  try {
+    res = await fetch(new URL(path, config.endpoint), {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs ?? config.timeoutMs ?? 30000),
+    });
+  } catch (err) {
+    return fail(isTimeoutError(err) ? "timeout" : "refused");
+  }
+  if (!res.ok) return fail("http-error");
+
+  let data;
+  try { data = await res.json(); } catch { return fail("invalid-json"); }
+
+  let value;
+  try { value = JSON.parse(extractContent(config.api, data)); } catch { return fail("invalid-json"); }
+
+  if (!validateSchema(value, schema)) return fail("schema-mismatch");
+  return finish({ ok: true, value });
+}

package/lib/README.md

@@ -7,6 +7,10 @@ Planned modules (**TASK-1.2**): `project-root` · `gate-runner` (Stop-hook harne
 · `selfcontained` (HTML verifier) · `lifecycle` (status-cannot-exceed-proven-artifacts) ·
 `installer` · `dates` · `template`.
 
+Also shipped: `structured-offload` — schema-validated, fail-soft calls to a local
+Ollama/OpenAI-compatible endpoint, config-driven (`.claude/structured-offload.json`),
+opt-in and absent-by-default. See `docs/wiki/chassis.md`.
+
 Also shipped here: `handoff-protocol.md` — a stamped copy of the canonical
 `docs/handoff-protocol.md` (re-stamped by `scripts/sync-shared.mjs`), so skills can reference
 the protocol as `${CLAUDE_PLUGIN_ROOT}/lib/handoff-protocol.md` from an installed plugin.

package/lib/board-mirror.mjs

@@ -264,12 +264,23 @@ export function isPausedLink(link) {
  * Indexes are POSITIONAL (1-based) within the block — a position, not an identity. A reordered
  * block renumbers.
  *
- * `parseSpecPhasesBlock` tolerates two normalizations a live Jira write→read round-trip is known
- * to introduce on EVERY read (same findings file): a blank line inserted immediately after
- * BEGIN (skipped here — a blank line is never a checkbox line) and two trailing spaces appended
+ * `parseSpecPhasesBlock` tolerates THREE normalizations a live Jira write→read round-trip is
+ * known to introduce on EVERY read (same findings file): a blank line inserted immediately after
+ * BEGIN (skipped here — a blank line is never a checkbox line), two trailing spaces appended
  * to the LAST checkbox line (needs no extra handling: TASK_LINE's own `(\S.*?)\s*$` already
- * strips trailing whitespace from the captured text). Reuses TASK_LINE from spec-derive.mjs
- * rather than a third checkbox regex. */
+ * strips trailing whitespace from the captured text), and two trailing spaces appended to the
+ * END MARKER LINE itself (verified live 2026-09-10, spec 056 phase 2 — the slice on
+ * indexOf(END) leaves them outside every item, so they never reach the parse). Reuses TASK_LINE
+ * from spec-derive.mjs rather than a third checkbox regex.
+ *
+ * WHY THE RENDERER RIGHT-TRIMS (spec 056 phase 3, verified live): that END-marker whitespace
+ * COMPOUNDS if echoed back. Read 2 spaces, write them back unchanged, and the next read returns
+ * 4 — then 6, and so on, because Jira appends its own on top of whatever it is given. Phase 1
+ * recorded the cycle as "idempotent, not degrading", which held for the checkbox lines it
+ * measured but NOT for the END marker. `renderSpecPhasesBlock` emits a clean marker with no
+ * trailing whitespace, which re-normalizes every cycle back to a constant 2 (confirmed by a
+ * live write of a clean marker returning exactly 2). Splice the rendered block between the
+ * existing markers rather than preserving the read bytes, and the growth cannot start. */
 
 const SPEC_PHASES_BEGIN = "<!-- spec-phases BEGIN -->";
 const SPEC_PHASES_END = "<!-- spec-phases END -->";
@@ -402,6 +413,12 @@ export function projectBacklog(root) {
  *  `jira` by adding one key here; no `if (provider === "...")` branch belongs anywhere. */
 export const providers = {
   backlog: { requiresSync: false, project: projectBacklog },
+  // spec 056 R1. `project: null` is not an omission — it is the TYPE-LEVEL statement that this
+  // provider cannot be projected by `node` alone (it needs MCP, hence a skill). Registering it
+  // is what activates spec 052 R5's `--check` behavior and spec 053 R3/R4's staleness and
+  // missing-mirror findings for a Jira host. No `if (provider === "jira")` branch belongs
+  // anywhere: the shape of this entry carries the distinction.
+  jira: { requiresSync: true, project: null },
 };
 
 /* ── `.board.json` config schema (spec 054) — a SEPARATE, smaller table from `providers`
@@ -462,10 +479,65 @@ export function validateBoardConfig(config) {
       if (!sub[field]) problems.push(`${name}.${field}: required for provider "${name}"`);
     if (sub.statusMap !== undefined && (typeof sub.statusMap !== "object" || Array.isArray(sub.statusMap) || sub.statusMap === null))
       problems.push(`${name}.statusMap: expected object, got ${Array.isArray(sub.statusMap) ? "array" : typeof sub.statusMap}`);
+    if (sub.statusReadMap !== undefined && (typeof sub.statusReadMap !== "object" || Array.isArray(sub.statusReadMap) || sub.statusReadMap === null))
+      problems.push(`${name}.statusReadMap: expected object, got ${Array.isArray(sub.statusReadMap) ? "array" : typeof sub.statusReadMap}`);
+    // The injectivity rule differs BY DIRECTION and that asymmetry is the whole point (spec 056
+    // Phase 2 / the 2026-09-10 operator ruling). `statusMap` is bridge -> site: it names the one
+    // canonical WRITE target per bridge status, so two bridge statuses sharing a site status
+    // makes the reverse read ambiguous and is an ERROR. `statusReadMap` is site -> bridge and is
+    // many-to-one BY DESIGN (a 15-status workflow collapsing onto 3), so it is deliberately
+    // exempt. Silently picking a winner would make verdicts depend on key order.
+    if (sub.statusMap && typeof sub.statusMap === "object" && !Array.isArray(sub.statusMap)) {
+      const seen = new Map();
+      for (const [bridge, site] of Object.entries(sub.statusMap)) {
+        if (typeof site !== "string") continue;
+        const prior = seen.get(site);
+        if (prior !== undefined)
+          problems.push(`${name}.statusMap: non-injective — "${prior}" and "${bridge}" both map to site status "${site}"; the reverse read would be ambiguous`);
+        else seen.set(site, bridge);
+      }
+    }
   }
   return problems;
 }
 
+/* ── status mapping, both directions (spec 054 R1 + spec 056 Phase 2's ratified amendment) ──
+ *
+ * Two fields, because the two directions have genuinely different shapes and one field cannot
+ * honestly carry both:
+ *
+ *   bridge status ──statusMap──▶ site status      (WRITE: injective, one canonical target)
+ *   site status ──statusReadMap──▶ bridge status  (READ: many-to-one BY DESIGN)
+ *
+ * The live workflow that forced this had FIFTEEN statuses against the bridge's three
+ * (`bridge.mjs`'s RANK: to do / in progress / done). Collapsing 15 onto 3 is inherently
+ * many-to-one, while the write direction must pick exactly one target per bridge status.
+ * See specs/056-jira-provider/findings/phase-2-operator-rulings.md, ruling 2.
+ *
+ * Both directions FALL THROUGH UNCHANGED on a miss — spec 054 R1's stated rule, kept here so a
+ * host with no map at all behaves exactly as it did before either field existed. */
+
+/** Map a bridge status to the site's workflow status for a WRITE. Falls through unchanged. */
+export function toSiteStatus(bridgeStatus, config = {}) {
+  return config?.statusMap?.[bridgeStatus] ?? bridgeStatus;
+}
+
+/** Map a site workflow status back to the bridge's vocabulary for a READ. Prefers the explicit
+ *  many-to-one `statusReadMap`; with none, inverts `statusMap` (so a host that predates
+ *  `statusReadMap` keeps its exact prior behavior). Falls through unchanged on a miss — the
+ *  caller's `verdict()` then reports "unknown" for a status outside the vocabulary rather than
+ *  this function guessing one. */
+export function toBridgeStatus(siteStatus, config = {}) {
+  const read = config?.statusReadMap;
+  if (read && typeof read === "object" && !Array.isArray(read) && read[siteStatus] !== undefined)
+    return read[siteStatus];
+  const write = config?.statusMap;
+  if (write && typeof write === "object" && !Array.isArray(write)) {
+    for (const [bridge, site] of Object.entries(write)) if (site === siteStatus) return bridge;
+  }
+  return siteStatus;
+}
+
 /** Run git argv `args` in `cwd`. Never throws — a git failure is data, not an exception,
  *  matching grounding-wiki/gates/repin-window.mjs's `git()` helper shape (spawnSync, argv
  *  array so there is no shell, utf8 encoding). Returns `{ status, out }`; `status` is `null`

package/lib/structured-offload.mjs

@@ -0,0 +1,140 @@
+// structured-offload.mjs — schema-validated calls to a local model, fail-soft always.
+//
+// `offload({ prompt, schema, config, timeoutMs })` asks a local Ollama or
+// OpenAI-compatible endpoint to answer `prompt`, constrained to `schema` at the backend
+// (Ollama `format`, OpenAI-compatible `response_format: json_schema`) so the model is
+// structurally prevented from returning prose. The result is validated again on this
+// side against the same schema. NEVER throws: every failure path — unset config,
+// timeout, connection refused, non-2xx, invalid JSON, schema mismatch — resolves to
+// `{ ok: false, reason, residue }` and the caller does the work in-session, exactly as
+// if this module did not exist.
+//
+// `config` is loaded by `loadConfig(root)` from `<root>/.claude/structured-offload.json`
+// (absent/unreadable/malformed -> null -> `reason: 'unconfigured'`), kept separate from
+// `offload` so tests can hand it a stub-server config directly without touching disk.
+//
+// Config shape: `{ endpoint, api: 'ollama'|'openai', model, timeoutMs?, residuePath? }`.
+//
+// Schema checker (minimal subset — extend only when a consumer needs more):
+//   - `type`: 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean'
+//   - `required`: array of property names that must exist on an object value
+//   - `properties`: per-key sub-schemas, checked recursively
+//   - `enum`: value must be one of the listed members
+//   - `items`: sub-schema every array element must satisfy
+// ponytail: full JSON Schema (oneOf/anyOf/patternProperties/formats/…) is not
+// implemented; the checked subset is what closed-enum/path-lookup callers need.
+//
+// `residue`: `{ backend, model, outcome: 'validated'|'fallback', reason?, ms }`,
+// returned on every call and appended as a JSON line to `config.residuePath` when set.
+
+import { readFileSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Load and validate the config file, or null on any absence/parse/shape failure. */
+export function loadConfig(root) {
+  try {
+    const cfg = JSON.parse(readFileSync(join(root, ".claude", "structured-offload.json"), "utf8"));
+    if (!cfg || typeof cfg !== "object") return null;
+    if (!cfg.endpoint || !["ollama", "openai"].includes(cfg.api) || !cfg.model) return null;
+    return cfg;
+  } catch {
+    return null;
+  }
+}
+
+function isTimeoutError(err) {
+  return err?.name === "TimeoutError" || err?.name === "AbortError";
+}
+
+function buildRequest(config, prompt, schema) {
+  const messages = [{ role: "user", content: prompt }];
+  if (config.api === "ollama") {
+    return { path: "/api/chat", body: { model: config.model, messages, format: schema, stream: false } };
+  }
+  return {
+    path: "/v1/chat/completions",
+    body: {
+      model: config.model,
+      messages,
+      response_format: { type: "json_schema", json_schema: { name: "offload_response", strict: true, schema } },
+    },
+  };
+}
+
+function extractContent(api, data) {
+  return api === "ollama" ? data?.message?.content : data?.choices?.[0]?.message?.content;
+}
+
+/** The minimal schema subset documented in the module header. */
+export function validateSchema(value, schema) {
+  if (!schema) return true;
+  if (schema.enum) return schema.enum.includes(value);
+  switch (schema.type) {
+    case "object": {
+      if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+      for (const key of schema.required || []) if (!(key in value)) return false;
+      if (schema.properties) {
+        for (const [key, sub] of Object.entries(schema.properties)) {
+          if (key in value && !validateSchema(value[key], sub)) return false;
+        }
+      }
+      return true;
+    }
+    case "array":
+      return Array.isArray(value) && (!schema.items || value.every((v) => validateSchema(v, schema.items)));
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number";
+    case "integer":
+      return Number.isInteger(value);
+    case "boolean":
+      return typeof value === "boolean";
+    default:
+      return true;
+  }
+}
+
+/** Async, never-throwing: see module header for the full contract. */
+export async function offload({ prompt, schema, config, timeoutMs } = {}) {
+  const start = Date.now();
+  const backend = config?.api;
+  const model = config?.model;
+
+  function finish(result) {
+    const residue = { backend, model, outcome: result.ok ? "validated" : "fallback", ms: Date.now() - start };
+    if (!result.ok) residue.reason = result.reason;
+    if (config?.residuePath) {
+      try { appendFileSync(config.residuePath, JSON.stringify(residue) + "\n"); } catch { /* residue is best-effort */ }
+    }
+    return { ...result, residue };
+  }
+  const fail = (reason) => finish({ ok: false, reason });
+
+  if (!config || !config.endpoint || !["ollama", "openai"].includes(config.api) || !config.model) {
+    return fail("unconfigured");
+  }
+
+  const { path, body } = buildRequest(config, prompt, schema);
+  let res;
+  try {
+    res = await fetch(new URL(path, config.endpoint), {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs ?? config.timeoutMs ?? 30000),
+    });
+  } catch (err) {
+    return fail(isTimeoutError(err) ? "timeout" : "refused");
+  }
+  if (!res.ok) return fail("http-error");
+
+  let data;
+  try { data = await res.json(); } catch { return fail("invalid-json"); }
+
+  let value;
+  try { value = JSON.parse(extractContent(config.api, data)); } catch { return fail("invalid-json"); }
+
+  if (!validateSchema(value, schema)) return fail("schema-mismatch");
+  return finish({ ok: true, value });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisflux/gates",
-  "version": "0.62.0",
+  "version": "0.63.1",
   "description": "praxisflux gate checks as a zero-dependency CLI (spec-bridge, wiki-freshness, course) — status can't exceed proven artifacts",
   "license": "MIT",
   "repository": {

package/spec-bridge/lib/README.md

@@ -7,6 +7,10 @@ Planned modules (**TASK-1.2**): `project-root` · `gate-runner` (Stop-hook harne
 · `selfcontained` (HTML verifier) · `lifecycle` (status-cannot-exceed-proven-artifacts) ·
 `installer` · `dates` · `template`.
 
+Also shipped: `structured-offload` — schema-validated, fail-soft calls to a local
+Ollama/OpenAI-compatible endpoint, config-driven (`.claude/structured-offload.json`),
+opt-in and absent-by-default. See `docs/wiki/chassis.md`.
+
 Also shipped here: `handoff-protocol.md` — a stamped copy of the canonical
 `docs/handoff-protocol.md` (re-stamped by `scripts/sync-shared.mjs`), so skills can reference
 the protocol as `${CLAUDE_PLUGIN_ROOT}/lib/handoff-protocol.md` from an installed plugin.

package/spec-bridge/lib/board-mirror.mjs

@@ -264,12 +264,23 @@ export function isPausedLink(link) {
  * Indexes are POSITIONAL (1-based) within the block — a position, not an identity. A reordered
  * block renumbers.
  *
- * `parseSpecPhasesBlock` tolerates two normalizations a live Jira write→read round-trip is known
- * to introduce on EVERY read (same findings file): a blank line inserted immediately after
- * BEGIN (skipped here — a blank line is never a checkbox line) and two trailing spaces appended
+ * `parseSpecPhasesBlock` tolerates THREE normalizations a live Jira write→read round-trip is
+ * known to introduce on EVERY read (same findings file): a blank line inserted immediately after
+ * BEGIN (skipped here — a blank line is never a checkbox line), two trailing spaces appended
  * to the LAST checkbox line (needs no extra handling: TASK_LINE's own `(\S.*?)\s*$` already
- * strips trailing whitespace from the captured text). Reuses TASK_LINE from spec-derive.mjs
- * rather than a third checkbox regex. */
+ * strips trailing whitespace from the captured text), and two trailing spaces appended to the
+ * END MARKER LINE itself (verified live 2026-09-10, spec 056 phase 2 — the slice on
+ * indexOf(END) leaves them outside every item, so they never reach the parse). Reuses TASK_LINE
+ * from spec-derive.mjs rather than a third checkbox regex.
+ *
+ * WHY THE RENDERER RIGHT-TRIMS (spec 056 phase 3, verified live): that END-marker whitespace
+ * COMPOUNDS if echoed back. Read 2 spaces, write them back unchanged, and the next read returns
+ * 4 — then 6, and so on, because Jira appends its own on top of whatever it is given. Phase 1
+ * recorded the cycle as "idempotent, not degrading", which held for the checkbox lines it
+ * measured but NOT for the END marker. `renderSpecPhasesBlock` emits a clean marker with no
+ * trailing whitespace, which re-normalizes every cycle back to a constant 2 (confirmed by a
+ * live write of a clean marker returning exactly 2). Splice the rendered block between the
+ * existing markers rather than preserving the read bytes, and the growth cannot start. */
 
 const SPEC_PHASES_BEGIN = "<!-- spec-phases BEGIN -->";
 const SPEC_PHASES_END = "<!-- spec-phases END -->";
@@ -402,6 +413,12 @@ export function projectBacklog(root) {
  *  `jira` by adding one key here; no `if (provider === "...")` branch belongs anywhere. */
 export const providers = {
   backlog: { requiresSync: false, project: projectBacklog },
+  // spec 056 R1. `project: null` is not an omission — it is the TYPE-LEVEL statement that this
+  // provider cannot be projected by `node` alone (it needs MCP, hence a skill). Registering it
+  // is what activates spec 052 R5's `--check` behavior and spec 053 R3/R4's staleness and
+  // missing-mirror findings for a Jira host. No `if (provider === "jira")` branch belongs
+  // anywhere: the shape of this entry carries the distinction.
+  jira: { requiresSync: true, project: null },
 };
 
 /* ── `.board.json` config schema (spec 054) — a SEPARATE, smaller table from `providers`
@@ -462,10 +479,65 @@ export function validateBoardConfig(config) {
       if (!sub[field]) problems.push(`${name}.${field}: required for provider "${name}"`);
     if (sub.statusMap !== undefined && (typeof sub.statusMap !== "object" || Array.isArray(sub.statusMap) || sub.statusMap === null))
       problems.push(`${name}.statusMap: expected object, got ${Array.isArray(sub.statusMap) ? "array" : typeof sub.statusMap}`);
+    if (sub.statusReadMap !== undefined && (typeof sub.statusReadMap !== "object" || Array.isArray(sub.statusReadMap) || sub.statusReadMap === null))
+      problems.push(`${name}.statusReadMap: expected object, got ${Array.isArray(sub.statusReadMap) ? "array" : typeof sub.statusReadMap}`);
+    // The injectivity rule differs BY DIRECTION and that asymmetry is the whole point (spec 056
+    // Phase 2 / the 2026-09-10 operator ruling). `statusMap` is bridge -> site: it names the one
+    // canonical WRITE target per bridge status, so two bridge statuses sharing a site status
+    // makes the reverse read ambiguous and is an ERROR. `statusReadMap` is site -> bridge and is
+    // many-to-one BY DESIGN (a 15-status workflow collapsing onto 3), so it is deliberately
+    // exempt. Silently picking a winner would make verdicts depend on key order.
+    if (sub.statusMap && typeof sub.statusMap === "object" && !Array.isArray(sub.statusMap)) {
+      const seen = new Map();
+      for (const [bridge, site] of Object.entries(sub.statusMap)) {
+        if (typeof site !== "string") continue;
+        const prior = seen.get(site);
+        if (prior !== undefined)
+          problems.push(`${name}.statusMap: non-injective — "${prior}" and "${bridge}" both map to site status "${site}"; the reverse read would be ambiguous`);
+        else seen.set(site, bridge);
+      }
+    }
   }
   return problems;
 }
 
+/* ── status mapping, both directions (spec 054 R1 + spec 056 Phase 2's ratified amendment) ──
+ *
+ * Two fields, because the two directions have genuinely different shapes and one field cannot
+ * honestly carry both:
+ *
+ *   bridge status ──statusMap──▶ site status      (WRITE: injective, one canonical target)
+ *   site status ──statusReadMap──▶ bridge status  (READ: many-to-one BY DESIGN)
+ *
+ * The live workflow that forced this had FIFTEEN statuses against the bridge's three
+ * (`bridge.mjs`'s RANK: to do / in progress / done). Collapsing 15 onto 3 is inherently
+ * many-to-one, while the write direction must pick exactly one target per bridge status.
+ * See specs/056-jira-provider/findings/phase-2-operator-rulings.md, ruling 2.
+ *
+ * Both directions FALL THROUGH UNCHANGED on a miss — spec 054 R1's stated rule, kept here so a
+ * host with no map at all behaves exactly as it did before either field existed. */
+
+/** Map a bridge status to the site's workflow status for a WRITE. Falls through unchanged. */
+export function toSiteStatus(bridgeStatus, config = {}) {
+  return config?.statusMap?.[bridgeStatus] ?? bridgeStatus;
+}
+
+/** Map a site workflow status back to the bridge's vocabulary for a READ. Prefers the explicit
+ *  many-to-one `statusReadMap`; with none, inverts `statusMap` (so a host that predates
+ *  `statusReadMap` keeps its exact prior behavior). Falls through unchanged on a miss — the
+ *  caller's `verdict()` then reports "unknown" for a status outside the vocabulary rather than
+ *  this function guessing one. */
+export function toBridgeStatus(siteStatus, config = {}) {
+  const read = config?.statusReadMap;
+  if (read && typeof read === "object" && !Array.isArray(read) && read[siteStatus] !== undefined)
+    return read[siteStatus];
+  const write = config?.statusMap;
+  if (write && typeof write === "object" && !Array.isArray(write)) {
+    for (const [bridge, site] of Object.entries(write)) if (site === siteStatus) return bridge;
+  }
+  return siteStatus;
+}
+
 /** Run git argv `args` in `cwd`. Never throws — a git failure is data, not an exception,
  *  matching grounding-wiki/gates/repin-window.mjs's `git()` helper shape (spawnSync, argv
  *  array so there is no shell, utf8 encoding). Returns `{ status, out }`; `status` is `null`

package/spec-bridge/lib/structured-offload.mjs

@@ -0,0 +1,140 @@
+// structured-offload.mjs — schema-validated calls to a local model, fail-soft always.
+//
+// `offload({ prompt, schema, config, timeoutMs })` asks a local Ollama or
+// OpenAI-compatible endpoint to answer `prompt`, constrained to `schema` at the backend
+// (Ollama `format`, OpenAI-compatible `response_format: json_schema`) so the model is
+// structurally prevented from returning prose. The result is validated again on this
+// side against the same schema. NEVER throws: every failure path — unset config,
+// timeout, connection refused, non-2xx, invalid JSON, schema mismatch — resolves to
+// `{ ok: false, reason, residue }` and the caller does the work in-session, exactly as
+// if this module did not exist.
+//
+// `config` is loaded by `loadConfig(root)` from `<root>/.claude/structured-offload.json`
+// (absent/unreadable/malformed -> null -> `reason: 'unconfigured'`), kept separate from
+// `offload` so tests can hand it a stub-server config directly without touching disk.
+//
+// Config shape: `{ endpoint, api: 'ollama'|'openai', model, timeoutMs?, residuePath? }`.
+//
+// Schema checker (minimal subset — extend only when a consumer needs more):
+//   - `type`: 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean'
+//   - `required`: array of property names that must exist on an object value
+//   - `properties`: per-key sub-schemas, checked recursively
+//   - `enum`: value must be one of the listed members
+//   - `items`: sub-schema every array element must satisfy
+// ponytail: full JSON Schema (oneOf/anyOf/patternProperties/formats/…) is not
+// implemented; the checked subset is what closed-enum/path-lookup callers need.
+//
+// `residue`: `{ backend, model, outcome: 'validated'|'fallback', reason?, ms }`,
+// returned on every call and appended as a JSON line to `config.residuePath` when set.
+
+import { readFileSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Load and validate the config file, or null on any absence/parse/shape failure. */
+export function loadConfig(root) {
+  try {
+    const cfg = JSON.parse(readFileSync(join(root, ".claude", "structured-offload.json"), "utf8"));
+    if (!cfg || typeof cfg !== "object") return null;
+    if (!cfg.endpoint || !["ollama", "openai"].includes(cfg.api) || !cfg.model) return null;
+    return cfg;
+  } catch {
+    return null;
+  }
+}
+
+function isTimeoutError(err) {
+  return err?.name === "TimeoutError" || err?.name === "AbortError";
+}
+
+function buildRequest(config, prompt, schema) {
+  const messages = [{ role: "user", content: prompt }];
+  if (config.api === "ollama") {
+    return { path: "/api/chat", body: { model: config.model, messages, format: schema, stream: false } };
+  }
+  return {
+    path: "/v1/chat/completions",
+    body: {
+      model: config.model,
+      messages,
+      response_format: { type: "json_schema", json_schema: { name: "offload_response", strict: true, schema } },
+    },
+  };
+}
+
+function extractContent(api, data) {
+  return api === "ollama" ? data?.message?.content : data?.choices?.[0]?.message?.content;
+}
+
+/** The minimal schema subset documented in the module header. */
+export function validateSchema(value, schema) {
+  if (!schema) return true;
+  if (schema.enum) return schema.enum.includes(value);
+  switch (schema.type) {
+    case "object": {
+      if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+      for (const key of schema.required || []) if (!(key in value)) return false;
+      if (schema.properties) {
+        for (const [key, sub] of Object.entries(schema.properties)) {
+          if (key in value && !validateSchema(value[key], sub)) return false;
+        }
+      }
+      return true;
+    }
+    case "array":
+      return Array.isArray(value) && (!schema.items || value.every((v) => validateSchema(v, schema.items)));
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number";
+    case "integer":
+      return Number.isInteger(value);
+    case "boolean":
+      return typeof value === "boolean";
+    default:
+      return true;
+  }
+}
+
+/** Async, never-throwing: see module header for the full contract. */
+export async function offload({ prompt, schema, config, timeoutMs } = {}) {
+  const start = Date.now();
+  const backend = config?.api;
+  const model = config?.model;
+
+  function finish(result) {
+    const residue = { backend, model, outcome: result.ok ? "validated" : "fallback", ms: Date.now() - start };
+    if (!result.ok) residue.reason = result.reason;
+    if (config?.residuePath) {
+      try { appendFileSync(config.residuePath, JSON.stringify(residue) + "\n"); } catch { /* residue is best-effort */ }
+    }
+    return { ...result, residue };
+  }
+  const fail = (reason) => finish({ ok: false, reason });
+
+  if (!config || !config.endpoint || !["ollama", "openai"].includes(config.api) || !config.model) {
+    return fail("unconfigured");
+  }
+
+  const { path, body } = buildRequest(config, prompt, schema);
+  let res;
+  try {
+    res = await fetch(new URL(path, config.endpoint), {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs ?? config.timeoutMs ?? 30000),
+    });
+  } catch (err) {
+    return fail(isTimeoutError(err) ? "timeout" : "refused");
+  }
+  if (!res.ok) return fail("http-error");
+
+  let data;
+  try { data = await res.json(); } catch { return fail("invalid-json"); }
+
+  let value;
+  try { value = JSON.parse(extractContent(config.api, data)); } catch { return fail("invalid-json"); }
+
+  if (!validateSchema(value, schema)) return fail("schema-mismatch");
+  return finish({ ok: true, value });
+}