@praxisflux/gates 0.61.1 → 0.63.0

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

@@ -10,6 +10,7 @@
 //     "links": [
 //       { "id": "TASK-109", "status": "In Progress", "specDir": "specs/052-board-adapter-seam",
 //         "acs": [ { "index": 1, "checked": true, "text": "Spec phase: Seam" } ],
+//         "labels": ["paused"],
 //         "observedAt": "<ISO 8601>", "observedSha": "<git sha>" }
 //     ]
 //   }
@@ -20,6 +21,15 @@
 // logic. `observedAt` / `observedSha` exist for providers whose projection needs a model
 // (MCP-backed boards); a deterministic provider MAY set them, nothing requires it to.
 //
+// `labels` (spec 055 R4, additive to spec 052's schema) is an OPTIONAL array of strings per
+// link. A mirror that omits it still validates — `projectBacklog` itself omits the key for a
+// task with no labels, so an unlabelled task's link stays byte-identical to before this field
+// existed. It exists so `docs/task-labels.md`'s Reserved `paused` label — machine-read by
+// `pdlc:sweep`'s paused-lane doctrine — can be resolved from the mirror alone, without
+// assuming `backlog/tasks/*.md` is present to read frontmatter from directly (the case a
+// Jira-only project is in; see `isPausedLink` below). Both providers project it; neither is
+// required to emit it for an unlabelled link.
+//
 // `schema` is an integer; a `schema` this module does not recognize is a HARD ERROR on read —
 // never a silent best-effort parse (fail-closed, docs/wiki/gates-convention.md). Unknown
 // top-level and per-link keys round-trip: read a mirror, write it back, and every key this
@@ -60,6 +70,7 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from
 import { join, dirname, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { runAsCli } from "./cli.mjs";
+import { TASK_LINE } from "./spec-derive.mjs";
 
 /** The only schema this module understands. */
 export const CURRENT_SCHEMA = 1;
@@ -115,7 +126,7 @@ export function readMirror(root) {
 }
 
 const TOP_KEYS = ["schema", "provider", "generatedAt", "links"];
-const LINK_KEYS = ["id", "status", "specDir", "acs", "observedAt", "observedSha"];
+const LINK_KEYS = ["id", "status", "specDir", "acs", "labels", "observedAt", "observedSha"];
 const AC_KEYS = ["index", "checked", "text"];
 
 /** Rebuild `obj` with `knownKeys` first (in that order, when present) and every other own key
@@ -193,6 +204,19 @@ export function validateMirror(mirror) {
       seenSpecDirs.add(link.specDir);
     }
 
+    // labels is OPTIONAL (spec 055 R4) — a missing key is valid (backward compat with every
+    // mirror written before this field existed); present-but-malformed is an error naming the
+    // offending link.
+    if (link.labels !== undefined) {
+      if (!Array.isArray(link.labels)) {
+        problems.push(`${where}.labels: expected array, got ${typeof link.labels}`);
+      } else {
+        link.labels.forEach((l, k) => {
+          if (typeof l !== "string") problems.push(`${where}.labels[${k}]: expected string, got ${typeof l}`);
+        });
+      }
+    }
+
     if (!req(link.acs, `${where}.acs`, "array")) return;
     let prev = -Infinity;
     link.acs.forEach((ac, j) => {
@@ -211,6 +235,89 @@ export function validateMirror(mirror) {
   return problems;
 }
 
+/** Is this mirror link paused (`docs/task-labels.md`'s Reserved `paused` label), read from
+ *  the mirror's OWN `labels` — never from `backlog/tasks/*.md`. This is the primitive
+ *  `pdlc:sweep`'s paused-lane doctrine (and any future conflict-analysis script) resolves
+ *  against, so a mirror-only project — no live board files to fall back on, the case a
+ *  Jira-only host is in — still excludes a parked branch's task from lane-conflict analysis
+ *  (spec 055 R4/AC #7). */
+export function isPausedLink(link) {
+  return Array.isArray(link?.labels) && link.labels.includes("paused");
+}
+
+/* ── the marked description block (spec 055 R2): render/parse pair for the Jira analogue of
+ * Backlog's AC:BEGIN/END block. Lives here, not a new lib/ module, because it produces and
+ * consumes exactly this file's own `acs` shape ([{ index, checked, text }]) and needs nothing
+ * else. Full contract: docs/board-verbs.md "R2 — the marked description block".
+ *
+ * Rules: text OUTSIDE the markers is human-authored and NEVER touched — neither function reads
+ * or writes past them. The block is REPLACED WHOLESALE; there is no partial-edit form. The
+ * `Spec: <dir>` marker line stays OUTSIDE the block — bridge.mjs's `MARKER`
+ * (`/^Spec:\s*(\S+?)\/?\s*$/m`) is unaffected either way, since it is anchored per-line and
+ * matches wherever a bare `Spec: ` line sits, block or no block (verified by fixture,
+ * test/board-mirror.test.mjs). ONE block per description: a second BEGIN or END is a
+ * validation error, not a merge. MARKDOWN ONLY — an `html`-format read or write is a contract
+ * violation, not a formatting choice: Jira's html rendering escapes the markers and swallows
+ * the END marker inside the final task-list `<li>` (verified live, spec 056 phase 1,
+ * specs/056-jira-provider/findings/phase-1-mcp-surface.md).
+ *
+ * Indexes are POSITIONAL (1-based) within the block — a position, not an identity. A reordered
+ * block renumbers.
+ *
+ * `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), 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 -->";
+
+/** Render items ([{ checked, text }], in order) as the block's exact text, markers included. */
+export function renderSpecPhasesBlock(items) {
+  const lines = items.map((it) => `- [${it.checked ? "x" : " "}] ${it.text}`);
+  return [SPEC_PHASES_BEGIN, ...lines, SPEC_PHASES_END].join("\n");
+}
+
+/**
+ * Parse a description (or any string containing at most one block) into
+ * [{ index, checked, text }], 1-based positional — [] when no block is present (absent is not
+ * an error; only a duplicated block is). Throws when more than one BEGIN or END marker is
+ * found, naming the counts.
+ */
+export function parseSpecPhasesBlock(text) {
+  const s = String(text ?? "");
+  const beginCount = s.split(SPEC_PHASES_BEGIN).length - 1;
+  const endCount = s.split(SPEC_PHASES_END).length - 1;
+  if (beginCount > 1 || endCount > 1)
+    throw new Error(`spec-phases block: found ${beginCount} BEGIN marker(s) and ${endCount} END marker(s) — exactly one block is allowed per description`);
+  const start = s.indexOf(SPEC_PHASES_BEGIN);
+  const stop = s.indexOf(SPEC_PHASES_END);
+  if (start === -1 || stop === -1) return [];
+  if (stop < start) throw new Error("spec-phases block: END marker precedes BEGIN marker");
+  const inner = s.slice(start + SPEC_PHASES_BEGIN.length, stop);
+  const items = [];
+  for (const line of inner.split("\n")) {
+    if (line.trim() === "") continue; // tolerates the blank line Jira inserts after BEGIN
+    const m = line.match(TASK_LINE);
+    if (!m) continue;
+    items.push({ index: items.length + 1, checked: m[1] !== " ", text: m[2] });
+  }
+  return items;
+}
+
 /* ── the backlog projector: parses backlog/tasks/*.md, moved from spec-bridge/gates/bridge.mjs ──
  *
  * Moved rather than duplicated (spec 052 phase 2): two parsers would silently drift the first
@@ -219,11 +326,37 @@ export function validateMirror(mirror) {
 
 const MARKER = /^Spec:\s*(\S+?)\/?\s*$/m;
 
+/** Parse a frontmatter block's `labels:` field — either Backlog.md's actual YAML block-list
+ *  form (`labels:\n  - a\n  - b\n`) or an inline form (`labels: []`, `labels: [a, b]`).
+ *  Returns [] when absent, empty, or unparseable — never throws. */
+function parseFrontmatterLabels(fm) {
+  const m = fm.match(/^labels:(.*)$/m);
+  if (!m) return [];
+  const strip = (s) => s.trim().replace(/^['"]|['"]$/g, "");
+  const rest = m[1].trim();
+  if (rest) {
+    const inline = rest.match(/^\[(.*)\]$/);
+    return inline ? inline[1].split(",").map(strip).filter(Boolean) : [];
+  }
+  const items = [];
+  for (const line of fm.slice(fm.indexOf(m[0]) + m[0].length).split("\n")) {
+    if (line.trim() === "") continue; // the blank remainder of the "labels:" line itself
+    const li = line.match(/^\s*-\s*(.+?)\s*$/);
+    if (!li) break;
+    items.push(strip(li[1]));
+  }
+  return items;
+}
+
 /**
- * Parse one Backlog task file. Returns { id, status, specDir, acs } for a linked task,
- * null for anything else (no marker, unreadable, or not a task file). `acs` is the task's
- * acceptance criteria as [{ index, checked, text }] read from the AC:BEGIN/END block —
- * still read-only; the plan command needs them to compute reconciling edits.
+ * Parse one Backlog task file. Returns { id, status, specDir, acs } for a linked task, null
+ * for anything else (no marker, unreadable, or not a task file). `acs` is the task's
+ * acceptance criteria as [{ index, checked, text }] read from the AC:BEGIN/END block — still
+ * read-only; the plan command needs them to compute reconciling edits. `labels` (spec 055
+ * R4) is included ONLY when the task's frontmatter `labels:` list is non-empty — an
+ * unlabelled task's return value stays byte-identical to before this field existed (this is
+ * load-bearing: test/spec-bridge.test.mjs asserts the exact shape and is frozen — specs
+ * 052-055 all state it must pass unmodified).
  */
 export function parseLinkedTask(raw) {
   const text = String(raw ?? "");
@@ -240,7 +373,10 @@ export function parseLinkedTask(raw) {
   if (block)
     for (const m of block[1].matchAll(/^- \[( |x|X)\] #(\d+)\s+(.*\S)\s*$/gm))
       acs.push({ index: +m[2], checked: m[1] !== " ", text: m[3] });
-  return { id, status, specDir: marker[1], acs };
+  const labels = parseFrontmatterLabels(fm[1]);
+  const linked = { id, status, specDir: marker[1], acs };
+  if (labels.length) linked.labels = labels;
+  return linked;
 }
 
 /** Scan <root>/backlog/tasks/*.md for linked tasks. Unreadable files are skipped. */
@@ -259,9 +395,13 @@ export function findLinkedTasks(root) {
 }
 
 /** The `backlog` provider's projector (spec 052 R4): `findLinkedTasks`' output reshaped to
- *  exactly the mirror's per-link fields (drops `file`). */
+ *  exactly the mirror's per-link fields (drops `file`). `labels` (spec 055 R4) rides straight
+ *  through — `parseLinkedTask` already omits it for an unlabelled task, so this needs no
+ *  extra logic to keep an unlabelled projection byte-identical to before this field existed. */
 export function projectBacklog(root) {
-  return findLinkedTasks(root).map(({ id, status, specDir, acs }) => ({ id, status, specDir, acs }));
+  return findLinkedTasks(root).map(({ id, status, specDir, acs, labels }) => (
+    labels ? { id, status, specDir, acs, labels } : { id, status, specDir, acs }
+  ));
 }
 
 /** Provider registry (spec 052 R4): provider name -> { requiresSync, project }.
@@ -273,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`
@@ -333,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/spec-derive.mjs

@@ -61,8 +61,11 @@ const PHASE_HEADING = /^##\s+(.+?)\s*$/;
 // identical to the old `/^\s*[-*]\s+\[([ xX])\]\s+\S/` (both require a non-space after the box;
 // per-line matching, so `.*?\s*$` always closes over the remainder) — this only adds capture
 // group 2, so parseTasks() output is byte-identical. The text feeds spec 050's blocking message
-// (AC #1: name the phase, the box, and the failing gate).
-const TASK_LINE = /^\s*[-*]\s+\[([ xX])\]\s+(\S.*?)\s*$/;
+// (AC #1: name the phase, the box, and the failing gate). Exported (spec 055 R2/Phase 3) so
+// lib/board-mirror.mjs's spec-phases block parser reuses this exact regex rather than writing a
+// third checkbox parser; per-line `(\S.*?)\s*$` already strips trailing whitespace from the
+// captured text, which is what makes it tolerate Jira's own trailing-space normalization too.
+export const TASK_LINE = /^\s*[-*]\s+\[([ xX])\]\s+(\S.*?)\s*$/;
 
 /** Strip Spec Kit's "Phase 3.1:" style prefix so phase names read as AC labels ("Setup"). */
 function phaseName(heading) {

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

@@ -10,6 +10,7 @@
 //     "links": [
 //       { "id": "TASK-109", "status": "In Progress", "specDir": "specs/052-board-adapter-seam",
 //         "acs": [ { "index": 1, "checked": true, "text": "Spec phase: Seam" } ],
+//         "labels": ["paused"],
 //         "observedAt": "<ISO 8601>", "observedSha": "<git sha>" }
 //     ]
 //   }
@@ -20,6 +21,15 @@
 // logic. `observedAt` / `observedSha` exist for providers whose projection needs a model
 // (MCP-backed boards); a deterministic provider MAY set them, nothing requires it to.
 //
+// `labels` (spec 055 R4, additive to spec 052's schema) is an OPTIONAL array of strings per
+// link. A mirror that omits it still validates — `projectBacklog` itself omits the key for a
+// task with no labels, so an unlabelled task's link stays byte-identical to before this field
+// existed. It exists so `docs/task-labels.md`'s Reserved `paused` label — machine-read by
+// `pdlc:sweep`'s paused-lane doctrine — can be resolved from the mirror alone, without
+// assuming `backlog/tasks/*.md` is present to read frontmatter from directly (the case a
+// Jira-only project is in; see `isPausedLink` below). Both providers project it; neither is
+// required to emit it for an unlabelled link.
+//
 // `schema` is an integer; a `schema` this module does not recognize is a HARD ERROR on read —
 // never a silent best-effort parse (fail-closed, docs/wiki/gates-convention.md). Unknown
 // top-level and per-link keys round-trip: read a mirror, write it back, and every key this
@@ -60,6 +70,7 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from
 import { join, dirname, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { runAsCli } from "./cli.mjs";
+import { TASK_LINE } from "./spec-derive.mjs";
 
 /** The only schema this module understands. */
 export const CURRENT_SCHEMA = 1;
@@ -115,7 +126,7 @@ export function readMirror(root) {
 }
 
 const TOP_KEYS = ["schema", "provider", "generatedAt", "links"];
-const LINK_KEYS = ["id", "status", "specDir", "acs", "observedAt", "observedSha"];
+const LINK_KEYS = ["id", "status", "specDir", "acs", "labels", "observedAt", "observedSha"];
 const AC_KEYS = ["index", "checked", "text"];
 
 /** Rebuild `obj` with `knownKeys` first (in that order, when present) and every other own key
@@ -193,6 +204,19 @@ export function validateMirror(mirror) {
       seenSpecDirs.add(link.specDir);
     }
 
+    // labels is OPTIONAL (spec 055 R4) — a missing key is valid (backward compat with every
+    // mirror written before this field existed); present-but-malformed is an error naming the
+    // offending link.
+    if (link.labels !== undefined) {
+      if (!Array.isArray(link.labels)) {
+        problems.push(`${where}.labels: expected array, got ${typeof link.labels}`);
+      } else {
+        link.labels.forEach((l, k) => {
+          if (typeof l !== "string") problems.push(`${where}.labels[${k}]: expected string, got ${typeof l}`);
+        });
+      }
+    }
+
     if (!req(link.acs, `${where}.acs`, "array")) return;
     let prev = -Infinity;
     link.acs.forEach((ac, j) => {
@@ -211,6 +235,89 @@ export function validateMirror(mirror) {
   return problems;
 }
 
+/** Is this mirror link paused (`docs/task-labels.md`'s Reserved `paused` label), read from
+ *  the mirror's OWN `labels` — never from `backlog/tasks/*.md`. This is the primitive
+ *  `pdlc:sweep`'s paused-lane doctrine (and any future conflict-analysis script) resolves
+ *  against, so a mirror-only project — no live board files to fall back on, the case a
+ *  Jira-only host is in — still excludes a parked branch's task from lane-conflict analysis
+ *  (spec 055 R4/AC #7). */
+export function isPausedLink(link) {
+  return Array.isArray(link?.labels) && link.labels.includes("paused");
+}
+
+/* ── the marked description block (spec 055 R2): render/parse pair for the Jira analogue of
+ * Backlog's AC:BEGIN/END block. Lives here, not a new lib/ module, because it produces and
+ * consumes exactly this file's own `acs` shape ([{ index, checked, text }]) and needs nothing
+ * else. Full contract: docs/board-verbs.md "R2 — the marked description block".
+ *
+ * Rules: text OUTSIDE the markers is human-authored and NEVER touched — neither function reads
+ * or writes past them. The block is REPLACED WHOLESALE; there is no partial-edit form. The
+ * `Spec: <dir>` marker line stays OUTSIDE the block — bridge.mjs's `MARKER`
+ * (`/^Spec:\s*(\S+?)\/?\s*$/m`) is unaffected either way, since it is anchored per-line and
+ * matches wherever a bare `Spec: ` line sits, block or no block (verified by fixture,
+ * test/board-mirror.test.mjs). ONE block per description: a second BEGIN or END is a
+ * validation error, not a merge. MARKDOWN ONLY — an `html`-format read or write is a contract
+ * violation, not a formatting choice: Jira's html rendering escapes the markers and swallows
+ * the END marker inside the final task-list `<li>` (verified live, spec 056 phase 1,
+ * specs/056-jira-provider/findings/phase-1-mcp-surface.md).
+ *
+ * Indexes are POSITIONAL (1-based) within the block — a position, not an identity. A reordered
+ * block renumbers.
+ *
+ * `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), 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 -->";
+
+/** Render items ([{ checked, text }], in order) as the block's exact text, markers included. */
+export function renderSpecPhasesBlock(items) {
+  const lines = items.map((it) => `- [${it.checked ? "x" : " "}] ${it.text}`);
+  return [SPEC_PHASES_BEGIN, ...lines, SPEC_PHASES_END].join("\n");
+}
+
+/**
+ * Parse a description (or any string containing at most one block) into
+ * [{ index, checked, text }], 1-based positional — [] when no block is present (absent is not
+ * an error; only a duplicated block is). Throws when more than one BEGIN or END marker is
+ * found, naming the counts.
+ */
+export function parseSpecPhasesBlock(text) {
+  const s = String(text ?? "");
+  const beginCount = s.split(SPEC_PHASES_BEGIN).length - 1;
+  const endCount = s.split(SPEC_PHASES_END).length - 1;
+  if (beginCount > 1 || endCount > 1)
+    throw new Error(`spec-phases block: found ${beginCount} BEGIN marker(s) and ${endCount} END marker(s) — exactly one block is allowed per description`);
+  const start = s.indexOf(SPEC_PHASES_BEGIN);
+  const stop = s.indexOf(SPEC_PHASES_END);
+  if (start === -1 || stop === -1) return [];
+  if (stop < start) throw new Error("spec-phases block: END marker precedes BEGIN marker");
+  const inner = s.slice(start + SPEC_PHASES_BEGIN.length, stop);
+  const items = [];
+  for (const line of inner.split("\n")) {
+    if (line.trim() === "") continue; // tolerates the blank line Jira inserts after BEGIN
+    const m = line.match(TASK_LINE);
+    if (!m) continue;
+    items.push({ index: items.length + 1, checked: m[1] !== " ", text: m[2] });
+  }
+  return items;
+}
+
 /* ── the backlog projector: parses backlog/tasks/*.md, moved from spec-bridge/gates/bridge.mjs ──
  *
  * Moved rather than duplicated (spec 052 phase 2): two parsers would silently drift the first
@@ -219,11 +326,37 @@ export function validateMirror(mirror) {
 
 const MARKER = /^Spec:\s*(\S+?)\/?\s*$/m;
 
+/** Parse a frontmatter block's `labels:` field — either Backlog.md's actual YAML block-list
+ *  form (`labels:\n  - a\n  - b\n`) or an inline form (`labels: []`, `labels: [a, b]`).
+ *  Returns [] when absent, empty, or unparseable — never throws. */
+function parseFrontmatterLabels(fm) {
+  const m = fm.match(/^labels:(.*)$/m);
+  if (!m) return [];
+  const strip = (s) => s.trim().replace(/^['"]|['"]$/g, "");
+  const rest = m[1].trim();
+  if (rest) {
+    const inline = rest.match(/^\[(.*)\]$/);
+    return inline ? inline[1].split(",").map(strip).filter(Boolean) : [];
+  }
+  const items = [];
+  for (const line of fm.slice(fm.indexOf(m[0]) + m[0].length).split("\n")) {
+    if (line.trim() === "") continue; // the blank remainder of the "labels:" line itself
+    const li = line.match(/^\s*-\s*(.+?)\s*$/);
+    if (!li) break;
+    items.push(strip(li[1]));
+  }
+  return items;
+}
+
 /**
- * Parse one Backlog task file. Returns { id, status, specDir, acs } for a linked task,
- * null for anything else (no marker, unreadable, or not a task file). `acs` is the task's
- * acceptance criteria as [{ index, checked, text }] read from the AC:BEGIN/END block —
- * still read-only; the plan command needs them to compute reconciling edits.
+ * Parse one Backlog task file. Returns { id, status, specDir, acs } for a linked task, null
+ * for anything else (no marker, unreadable, or not a task file). `acs` is the task's
+ * acceptance criteria as [{ index, checked, text }] read from the AC:BEGIN/END block — still
+ * read-only; the plan command needs them to compute reconciling edits. `labels` (spec 055
+ * R4) is included ONLY when the task's frontmatter `labels:` list is non-empty — an
+ * unlabelled task's return value stays byte-identical to before this field existed (this is
+ * load-bearing: test/spec-bridge.test.mjs asserts the exact shape and is frozen — specs
+ * 052-055 all state it must pass unmodified).
  */
 export function parseLinkedTask(raw) {
   const text = String(raw ?? "");
@@ -240,7 +373,10 @@ export function parseLinkedTask(raw) {
   if (block)
     for (const m of block[1].matchAll(/^- \[( |x|X)\] #(\d+)\s+(.*\S)\s*$/gm))
       acs.push({ index: +m[2], checked: m[1] !== " ", text: m[3] });
-  return { id, status, specDir: marker[1], acs };
+  const labels = parseFrontmatterLabels(fm[1]);
+  const linked = { id, status, specDir: marker[1], acs };
+  if (labels.length) linked.labels = labels;
+  return linked;
 }
 
 /** Scan <root>/backlog/tasks/*.md for linked tasks. Unreadable files are skipped. */
@@ -259,9 +395,13 @@ export function findLinkedTasks(root) {
 }
 
 /** The `backlog` provider's projector (spec 052 R4): `findLinkedTasks`' output reshaped to
- *  exactly the mirror's per-link fields (drops `file`). */
+ *  exactly the mirror's per-link fields (drops `file`). `labels` (spec 055 R4) rides straight
+ *  through — `parseLinkedTask` already omits it for an unlabelled task, so this needs no
+ *  extra logic to keep an unlabelled projection byte-identical to before this field existed. */
 export function projectBacklog(root) {
-  return findLinkedTasks(root).map(({ id, status, specDir, acs }) => ({ id, status, specDir, acs }));
+  return findLinkedTasks(root).map(({ id, status, specDir, acs, labels }) => (
+    labels ? { id, status, specDir, acs, labels } : { id, status, specDir, acs }
+  ));
 }
 
 /** Provider registry (spec 052 R4): provider name -> { requiresSync, project }.
@@ -273,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`
@@ -333,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/spec-derive.mjs

@@ -61,8 +61,11 @@ const PHASE_HEADING = /^##\s+(.+?)\s*$/;
 // identical to the old `/^\s*[-*]\s+\[([ xX])\]\s+\S/` (both require a non-space after the box;
 // per-line matching, so `.*?\s*$` always closes over the remainder) — this only adds capture
 // group 2, so parseTasks() output is byte-identical. The text feeds spec 050's blocking message
-// (AC #1: name the phase, the box, and the failing gate).
-const TASK_LINE = /^\s*[-*]\s+\[([ xX])\]\s+(\S.*?)\s*$/;
+// (AC #1: name the phase, the box, and the failing gate). Exported (spec 055 R2/Phase 3) so
+// lib/board-mirror.mjs's spec-phases block parser reuses this exact regex rather than writing a
+// third checkbox parser; per-line `(\S.*?)\s*$` already strips trailing whitespace from the
+// captured text, which is what makes it tolerate Jira's own trailing-space normalization too.
+export const TASK_LINE = /^\s*[-*]\s+\[([ xX])\]\s+(\S.*?)\s*$/;
 
 /** Strip Spec Kit's "Phase 3.1:" style prefix so phase names read as AC labels ("Setup"). */
 function phaseName(heading) {