@praxisflux/gates 0.59.0 → 0.59.3

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

@@ -36,6 +36,25 @@
 //
 // Dual-use: `node lib/board-mirror.mjs --check --root <dir>` mechanizes drift for a
 // deterministic provider and staleness for a model-backed one (see the CLI block below).
+//
+// `.board.json` (spec 054) is the OTHER file this module owns, and a different question from
+// the mirror above: `.board/links.json` is BOARD STATE (what's linked, its status);
+// `.board.json` is BOARD CONFIG (which provider a project uses, and that provider's
+// coordinates). Tracked, hand-editable, at the project root, outside every marker — same
+// posture as `.claude/model-tiers.json` (plant only when absent; doctrine points at the config;
+// the config is what you edit, not something generated). `loadBoardConfig`/`validateBoardConfig`
+// near the `providers` registry below read/check it.
+//
+// `.board.json`'s `statusMap` (bridge status -> site workflow status) composes with
+// `.spec-bridge.json`'s `statusVocabulary` (derivation stage -> bridge status, bridge.mjs:69)
+// at a DIFFERENT layer — the two do not merge, and this is the written precedence:
+//
+//   derivation stage ──statusVocabulary──▶ bridge status ──statusMap──▶ site workflow status
+//      (reviewing)                          ("In Review")                 ("In Review")
+//
+// Unmapped statuses fall through unchanged at either layer. Neither file's meaning changes;
+// this is only the stated relationship between them (two undocumented status mappings is a bug
+// factory).
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
@@ -256,6 +275,68 @@ export const providers = {
   backlog: { requiresSync: false, project: projectBacklog },
 };
 
+/* ── `.board.json` config schema (spec 054) — a SEPARATE, smaller table from `providers`
+ * above. `providers` is the projector registry (spec 052/056): provider name -> how to
+ * recompute the mirror. This table only knows the config-schema shape — which provider names
+ * are legal and which fields each requires — so `.board.json` can be validated today without
+ * pre-empting spec 056's ownership of adding `jira`'s projector entry to `providers`. Do NOT
+ * fold these two tables into one: that would re-couple config validation to projector
+ * implementation, which is exactly the coupling keeping them apart avoids. */
+const BOARD_CONFIG_PROVIDERS = {
+  backlog: { requiredFields: [] },
+  jira: { requiredFields: ["cloudId", "projectKey", "issueTypeName"] },
+};
+
+/** Load `<root>/.board.json`. Returns `{ provider: "backlog" }` when absent — spec 053's
+ *  backward-compatible default. Throws on malformed JSON (fail closed). Throws naming the known
+ *  providers on an unknown `provider` value — NEVER falls back to `backlog`: silently treating
+ *  a Jira project as a Backlog project is the exact silent no-op this feature exists to
+ *  remove. */
+export function loadBoardConfig(root) {
+  const path = join(root, ".board.json");
+  if (!existsSync(path)) return { provider: "backlog" };
+  const raw = readFileSync(path, "utf8");
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`${path}: malformed JSON (${e.message})`);
+  }
+  const name = config?.provider;
+  if (!BOARD_CONFIG_PROVIDERS[name])
+    throw new Error(`${path}: unknown board provider ${JSON.stringify(name)} (known: ${Object.keys(BOARD_CONFIG_PROVIDERS).join(", ")})`);
+  return config;
+}
+
+/** Validate a `.board.json` object (as returned by `loadBoardConfig` or built in memory).
+ *  Returns human-readable problems, empty when valid. Catches: `provider` as an array (one
+ *  board is the plan of record — a list is a validation error saying why) or other non-string,
+ *  an unknown provider name, a known provider missing one of its required fields (`jira` needs
+ *  `cloudId`/`projectKey`/`issueTypeName`), and a non-object `statusMap`. */
+export function validateBoardConfig(config) {
+  const problems = [];
+  if (!config || typeof config !== "object") {
+    problems.push("config: expected object");
+    return problems;
+  }
+  const name = config.provider;
+  if (Array.isArray(name)) {
+    problems.push("provider: expected a single string, got an array (one board is the plan of record)");
+  } else if (typeof name !== "string") {
+    problems.push(`provider: expected string, got ${name === undefined ? "missing" : typeof name}`);
+  } else if (!BOARD_CONFIG_PROVIDERS[name]) {
+    problems.push(`provider: unknown board provider "${name}" (known: ${Object.keys(BOARD_CONFIG_PROVIDERS).join(", ")})`);
+  } else {
+    const { requiredFields } = BOARD_CONFIG_PROVIDERS[name];
+    const sub = config[name] || {};
+    for (const field of requiredFields)
+      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}`);
+  }
+  return problems;
+}
+
 /** 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/board-mirror.mjs

@@ -36,6 +36,25 @@
 //
 // Dual-use: `node lib/board-mirror.mjs --check --root <dir>` mechanizes drift for a
 // deterministic provider and staleness for a model-backed one (see the CLI block below).
+//
+// `.board.json` (spec 054) is the OTHER file this module owns, and a different question from
+// the mirror above: `.board/links.json` is BOARD STATE (what's linked, its status);
+// `.board.json` is BOARD CONFIG (which provider a project uses, and that provider's
+// coordinates). Tracked, hand-editable, at the project root, outside every marker — same
+// posture as `.claude/model-tiers.json` (plant only when absent; doctrine points at the config;
+// the config is what you edit, not something generated). `loadBoardConfig`/`validateBoardConfig`
+// near the `providers` registry below read/check it.
+//
+// `.board.json`'s `statusMap` (bridge status -> site workflow status) composes with
+// `.spec-bridge.json`'s `statusVocabulary` (derivation stage -> bridge status, bridge.mjs:69)
+// at a DIFFERENT layer — the two do not merge, and this is the written precedence:
+//
+//   derivation stage ──statusVocabulary──▶ bridge status ──statusMap──▶ site workflow status
+//      (reviewing)                          ("In Review")                 ("In Review")
+//
+// Unmapped statuses fall through unchanged at either layer. Neither file's meaning changes;
+// this is only the stated relationship between them (two undocumented status mappings is a bug
+// factory).
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
@@ -256,6 +275,68 @@ export const providers = {
   backlog: { requiresSync: false, project: projectBacklog },
 };
 
+/* ── `.board.json` config schema (spec 054) — a SEPARATE, smaller table from `providers`
+ * above. `providers` is the projector registry (spec 052/056): provider name -> how to
+ * recompute the mirror. This table only knows the config-schema shape — which provider names
+ * are legal and which fields each requires — so `.board.json` can be validated today without
+ * pre-empting spec 056's ownership of adding `jira`'s projector entry to `providers`. Do NOT
+ * fold these two tables into one: that would re-couple config validation to projector
+ * implementation, which is exactly the coupling keeping them apart avoids. */
+const BOARD_CONFIG_PROVIDERS = {
+  backlog: { requiredFields: [] },
+  jira: { requiredFields: ["cloudId", "projectKey", "issueTypeName"] },
+};
+
+/** Load `<root>/.board.json`. Returns `{ provider: "backlog" }` when absent — spec 053's
+ *  backward-compatible default. Throws on malformed JSON (fail closed). Throws naming the known
+ *  providers on an unknown `provider` value — NEVER falls back to `backlog`: silently treating
+ *  a Jira project as a Backlog project is the exact silent no-op this feature exists to
+ *  remove. */
+export function loadBoardConfig(root) {
+  const path = join(root, ".board.json");
+  if (!existsSync(path)) return { provider: "backlog" };
+  const raw = readFileSync(path, "utf8");
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`${path}: malformed JSON (${e.message})`);
+  }
+  const name = config?.provider;
+  if (!BOARD_CONFIG_PROVIDERS[name])
+    throw new Error(`${path}: unknown board provider ${JSON.stringify(name)} (known: ${Object.keys(BOARD_CONFIG_PROVIDERS).join(", ")})`);
+  return config;
+}
+
+/** Validate a `.board.json` object (as returned by `loadBoardConfig` or built in memory).
+ *  Returns human-readable problems, empty when valid. Catches: `provider` as an array (one
+ *  board is the plan of record — a list is a validation error saying why) or other non-string,
+ *  an unknown provider name, a known provider missing one of its required fields (`jira` needs
+ *  `cloudId`/`projectKey`/`issueTypeName`), and a non-object `statusMap`. */
+export function validateBoardConfig(config) {
+  const problems = [];
+  if (!config || typeof config !== "object") {
+    problems.push("config: expected object");
+    return problems;
+  }
+  const name = config.provider;
+  if (Array.isArray(name)) {
+    problems.push("provider: expected a single string, got an array (one board is the plan of record)");
+  } else if (typeof name !== "string") {
+    problems.push(`provider: expected string, got ${name === undefined ? "missing" : typeof name}`);
+  } else if (!BOARD_CONFIG_PROVIDERS[name]) {
+    problems.push(`provider: unknown board provider "${name}" (known: ${Object.keys(BOARD_CONFIG_PROVIDERS).join(", ")})`);
+  } else {
+    const { requiredFields } = BOARD_CONFIG_PROVIDERS[name];
+    const sub = config[name] || {};
+    for (const field of requiredFields)
+      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}`);
+  }
+  return problems;
+}
+
 /** 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/board-mirror.mjs

@@ -36,6 +36,25 @@
 //
 // Dual-use: `node lib/board-mirror.mjs --check --root <dir>` mechanizes drift for a
 // deterministic provider and staleness for a model-backed one (see the CLI block below).
+//
+// `.board.json` (spec 054) is the OTHER file this module owns, and a different question from
+// the mirror above: `.board/links.json` is BOARD STATE (what's linked, its status);
+// `.board.json` is BOARD CONFIG (which provider a project uses, and that provider's
+// coordinates). Tracked, hand-editable, at the project root, outside every marker — same
+// posture as `.claude/model-tiers.json` (plant only when absent; doctrine points at the config;
+// the config is what you edit, not something generated). `loadBoardConfig`/`validateBoardConfig`
+// near the `providers` registry below read/check it.
+//
+// `.board.json`'s `statusMap` (bridge status -> site workflow status) composes with
+// `.spec-bridge.json`'s `statusVocabulary` (derivation stage -> bridge status, bridge.mjs:69)
+// at a DIFFERENT layer — the two do not merge, and this is the written precedence:
+//
+//   derivation stage ──statusVocabulary──▶ bridge status ──statusMap──▶ site workflow status
+//      (reviewing)                          ("In Review")                 ("In Review")
+//
+// Unmapped statuses fall through unchanged at either layer. Neither file's meaning changes;
+// this is only the stated relationship between them (two undocumented status mappings is a bug
+// factory).
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
@@ -256,6 +275,68 @@ export const providers = {
   backlog: { requiresSync: false, project: projectBacklog },
 };
 
+/* ── `.board.json` config schema (spec 054) — a SEPARATE, smaller table from `providers`
+ * above. `providers` is the projector registry (spec 052/056): provider name -> how to
+ * recompute the mirror. This table only knows the config-schema shape — which provider names
+ * are legal and which fields each requires — so `.board.json` can be validated today without
+ * pre-empting spec 056's ownership of adding `jira`'s projector entry to `providers`. Do NOT
+ * fold these two tables into one: that would re-couple config validation to projector
+ * implementation, which is exactly the coupling keeping them apart avoids. */
+const BOARD_CONFIG_PROVIDERS = {
+  backlog: { requiredFields: [] },
+  jira: { requiredFields: ["cloudId", "projectKey", "issueTypeName"] },
+};
+
+/** Load `<root>/.board.json`. Returns `{ provider: "backlog" }` when absent — spec 053's
+ *  backward-compatible default. Throws on malformed JSON (fail closed). Throws naming the known
+ *  providers on an unknown `provider` value — NEVER falls back to `backlog`: silently treating
+ *  a Jira project as a Backlog project is the exact silent no-op this feature exists to
+ *  remove. */
+export function loadBoardConfig(root) {
+  const path = join(root, ".board.json");
+  if (!existsSync(path)) return { provider: "backlog" };
+  const raw = readFileSync(path, "utf8");
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`${path}: malformed JSON (${e.message})`);
+  }
+  const name = config?.provider;
+  if (!BOARD_CONFIG_PROVIDERS[name])
+    throw new Error(`${path}: unknown board provider ${JSON.stringify(name)} (known: ${Object.keys(BOARD_CONFIG_PROVIDERS).join(", ")})`);
+  return config;
+}
+
+/** Validate a `.board.json` object (as returned by `loadBoardConfig` or built in memory).
+ *  Returns human-readable problems, empty when valid. Catches: `provider` as an array (one
+ *  board is the plan of record — a list is a validation error saying why) or other non-string,
+ *  an unknown provider name, a known provider missing one of its required fields (`jira` needs
+ *  `cloudId`/`projectKey`/`issueTypeName`), and a non-object `statusMap`. */
+export function validateBoardConfig(config) {
+  const problems = [];
+  if (!config || typeof config !== "object") {
+    problems.push("config: expected object");
+    return problems;
+  }
+  const name = config.provider;
+  if (Array.isArray(name)) {
+    problems.push("provider: expected a single string, got an array (one board is the plan of record)");
+  } else if (typeof name !== "string") {
+    problems.push(`provider: expected string, got ${name === undefined ? "missing" : typeof name}`);
+  } else if (!BOARD_CONFIG_PROVIDERS[name]) {
+    problems.push(`provider: unknown board provider "${name}" (known: ${Object.keys(BOARD_CONFIG_PROVIDERS).join(", ")})`);
+  } else {
+    const { requiredFields } = BOARD_CONFIG_PROVIDERS[name];
+    const sub = config[name] || {};
+    for (const field of requiredFields)
+      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}`);
+  }
+  return problems;
+}
+
 /** 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisflux/gates",
-  "version": "0.59.0",
+  "version": "0.59.3",
   "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/board-mirror.mjs

@@ -36,6 +36,25 @@
 //
 // Dual-use: `node lib/board-mirror.mjs --check --root <dir>` mechanizes drift for a
 // deterministic provider and staleness for a model-backed one (see the CLI block below).
+//
+// `.board.json` (spec 054) is the OTHER file this module owns, and a different question from
+// the mirror above: `.board/links.json` is BOARD STATE (what's linked, its status);
+// `.board.json` is BOARD CONFIG (which provider a project uses, and that provider's
+// coordinates). Tracked, hand-editable, at the project root, outside every marker — same
+// posture as `.claude/model-tiers.json` (plant only when absent; doctrine points at the config;
+// the config is what you edit, not something generated). `loadBoardConfig`/`validateBoardConfig`
+// near the `providers` registry below read/check it.
+//
+// `.board.json`'s `statusMap` (bridge status -> site workflow status) composes with
+// `.spec-bridge.json`'s `statusVocabulary` (derivation stage -> bridge status, bridge.mjs:69)
+// at a DIFFERENT layer — the two do not merge, and this is the written precedence:
+//
+//   derivation stage ──statusVocabulary──▶ bridge status ──statusMap──▶ site workflow status
+//      (reviewing)                          ("In Review")                 ("In Review")
+//
+// Unmapped statuses fall through unchanged at either layer. Neither file's meaning changes;
+// this is only the stated relationship between them (two undocumented status mappings is a bug
+// factory).
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
@@ -256,6 +275,68 @@ export const providers = {
   backlog: { requiresSync: false, project: projectBacklog },
 };
 
+/* ── `.board.json` config schema (spec 054) — a SEPARATE, smaller table from `providers`
+ * above. `providers` is the projector registry (spec 052/056): provider name -> how to
+ * recompute the mirror. This table only knows the config-schema shape — which provider names
+ * are legal and which fields each requires — so `.board.json` can be validated today without
+ * pre-empting spec 056's ownership of adding `jira`'s projector entry to `providers`. Do NOT
+ * fold these two tables into one: that would re-couple config validation to projector
+ * implementation, which is exactly the coupling keeping them apart avoids. */
+const BOARD_CONFIG_PROVIDERS = {
+  backlog: { requiredFields: [] },
+  jira: { requiredFields: ["cloudId", "projectKey", "issueTypeName"] },
+};
+
+/** Load `<root>/.board.json`. Returns `{ provider: "backlog" }` when absent — spec 053's
+ *  backward-compatible default. Throws on malformed JSON (fail closed). Throws naming the known
+ *  providers on an unknown `provider` value — NEVER falls back to `backlog`: silently treating
+ *  a Jira project as a Backlog project is the exact silent no-op this feature exists to
+ *  remove. */
+export function loadBoardConfig(root) {
+  const path = join(root, ".board.json");
+  if (!existsSync(path)) return { provider: "backlog" };
+  const raw = readFileSync(path, "utf8");
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`${path}: malformed JSON (${e.message})`);
+  }
+  const name = config?.provider;
+  if (!BOARD_CONFIG_PROVIDERS[name])
+    throw new Error(`${path}: unknown board provider ${JSON.stringify(name)} (known: ${Object.keys(BOARD_CONFIG_PROVIDERS).join(", ")})`);
+  return config;
+}
+
+/** Validate a `.board.json` object (as returned by `loadBoardConfig` or built in memory).
+ *  Returns human-readable problems, empty when valid. Catches: `provider` as an array (one
+ *  board is the plan of record — a list is a validation error saying why) or other non-string,
+ *  an unknown provider name, a known provider missing one of its required fields (`jira` needs
+ *  `cloudId`/`projectKey`/`issueTypeName`), and a non-object `statusMap`. */
+export function validateBoardConfig(config) {
+  const problems = [];
+  if (!config || typeof config !== "object") {
+    problems.push("config: expected object");
+    return problems;
+  }
+  const name = config.provider;
+  if (Array.isArray(name)) {
+    problems.push("provider: expected a single string, got an array (one board is the plan of record)");
+  } else if (typeof name !== "string") {
+    problems.push(`provider: expected string, got ${name === undefined ? "missing" : typeof name}`);
+  } else if (!BOARD_CONFIG_PROVIDERS[name]) {
+    problems.push(`provider: unknown board provider "${name}" (known: ${Object.keys(BOARD_CONFIG_PROVIDERS).join(", ")})`);
+  } else {
+    const { requiredFields } = BOARD_CONFIG_PROVIDERS[name];
+    const sub = config[name] || {};
+    for (const field of requiredFields)
+      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}`);
+  }
+  return problems;
+}
+
 /** 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`