@praxisflux/gates 0.61.0 → 0.62.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,78 @@ 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 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
+ * 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. */
+
+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 +315,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 +362,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 +384,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 }.

package/codebase-to-course/lib/gate-runner.mjs

@@ -18,6 +18,14 @@
 //
 // Contract (Claude Code Stop hook): stdin is JSON with { stop_hook_active, session_id, cwd, … };
 // exit 0 = allow the model to stop; exit 2 = block, and stderr becomes the message it sees.
+//
+// Root resolution in evaluate() (spec 062), most specific first: explicit { cwd } option ->
+// $CLAUDE_PROJECT_DIR -> input.cwd -> process.cwd(). An explicit argument is a caller naming a
+// directory on purpose and must never be silently overridden by an ambient variable. The env
+// var still outranks input.cwd: it's the harness's authoritative statement of the project root,
+// while input.cwd is merely where the hook happened to fire (a worktree, a subdir, wherever the
+// session sat). The only production caller, runStopHook below, passes no cwd, so this ordering
+// is byte-identical to before for the real Stop-hook path.
 
 /** Read all of stdin as a string (empty string on a TTY, so it's safe to run by hand). */
 export function readStdin() {
@@ -34,9 +42,9 @@ export function readStdin() {
  * Pure core: given the parsed hook input and the gates, return { block, message }.
  * Separated from process I/O so it is unit-testable.
  */
-export function evaluate(input, gates, { cwd = process.cwd() } = {}) {
+export function evaluate(input, gates, { cwd = undefined } = {}) {
   if (input && input.stop_hook_active === true) return { block: false, message: "", warnings: "" };
-  const start = process.env.CLAUDE_PROJECT_DIR || (input && input.cwd) || cwd;
+  const start = cwd || process.env.CLAUDE_PROJECT_DIR || (input && input.cwd) || process.cwd();
   const ctx = {
     sessionId: (input && input.session_id) || process.env.CLAUDE_CODE_SESSION_ID || null,
     input: input || {},

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,78 @@ 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 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
+ * 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. */
+
+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 +315,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 +362,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 +384,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 }.

package/grounding-wiki/lib/gate-runner.mjs

@@ -18,6 +18,14 @@
 //
 // Contract (Claude Code Stop hook): stdin is JSON with { stop_hook_active, session_id, cwd, … };
 // exit 0 = allow the model to stop; exit 2 = block, and stderr becomes the message it sees.
+//
+// Root resolution in evaluate() (spec 062), most specific first: explicit { cwd } option ->
+// $CLAUDE_PROJECT_DIR -> input.cwd -> process.cwd(). An explicit argument is a caller naming a
+// directory on purpose and must never be silently overridden by an ambient variable. The env
+// var still outranks input.cwd: it's the harness's authoritative statement of the project root,
+// while input.cwd is merely where the hook happened to fire (a worktree, a subdir, wherever the
+// session sat). The only production caller, runStopHook below, passes no cwd, so this ordering
+// is byte-identical to before for the real Stop-hook path.
 
 /** Read all of stdin as a string (empty string on a TTY, so it's safe to run by hand). */
 export function readStdin() {
@@ -34,9 +42,9 @@ export function readStdin() {
  * Pure core: given the parsed hook input and the gates, return { block, message }.
  * Separated from process I/O so it is unit-testable.
  */
-export function evaluate(input, gates, { cwd = process.cwd() } = {}) {
+export function evaluate(input, gates, { cwd = undefined } = {}) {
   if (input && input.stop_hook_active === true) return { block: false, message: "", warnings: "" };
-  const start = process.env.CLAUDE_PROJECT_DIR || (input && input.cwd) || cwd;
+  const start = cwd || process.env.CLAUDE_PROJECT_DIR || (input && input.cwd) || process.cwd();
   const ctx = {
     sessionId: (input && input.session_id) || process.env.CLAUDE_CODE_SESSION_ID || null,
     input: input || {},

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) {

package/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,78 @@ 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 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
+ * 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. */
+
+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 +315,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 +362,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 +384,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 }.

package/lib/gate-runner.mjs

@@ -18,6 +18,14 @@
 //
 // Contract (Claude Code Stop hook): stdin is JSON with { stop_hook_active, session_id, cwd, … };
 // exit 0 = allow the model to stop; exit 2 = block, and stderr becomes the message it sees.
+//
+// Root resolution in evaluate() (spec 062), most specific first: explicit { cwd } option ->
+// $CLAUDE_PROJECT_DIR -> input.cwd -> process.cwd(). An explicit argument is a caller naming a
+// directory on purpose and must never be silently overridden by an ambient variable. The env
+// var still outranks input.cwd: it's the harness's authoritative statement of the project root,
+// while input.cwd is merely where the hook happened to fire (a worktree, a subdir, wherever the
+// session sat). The only production caller, runStopHook below, passes no cwd, so this ordering
+// is byte-identical to before for the real Stop-hook path.
 
 /** Read all of stdin as a string (empty string on a TTY, so it's safe to run by hand). */
 export function readStdin() {
@@ -34,9 +42,9 @@ export function readStdin() {
  * Pure core: given the parsed hook input and the gates, return { block, message }.
  * Separated from process I/O so it is unit-testable.
  */
-export function evaluate(input, gates, { cwd = process.cwd() } = {}) {
+export function evaluate(input, gates, { cwd = undefined } = {}) {
   if (input && input.stop_hook_active === true) return { block: false, message: "", warnings: "" };
-  const start = process.env.CLAUDE_PROJECT_DIR || (input && input.cwd) || cwd;
+  const start = cwd || process.env.CLAUDE_PROJECT_DIR || (input && input.cwd) || process.cwd();
   const ctx = {
     sessionId: (input && input.session_id) || process.env.CLAUDE_CODE_SESSION_ID || null,
     input: input || {},

package/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisflux/gates",
-  "version": "0.61.0",
+  "version": "0.62.0",
   "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/gates/bridge.mjs

@@ -779,6 +779,76 @@ export function renderBacklog(id, intents) {
   return cmds;
 }
 
+/**
+ * Render one task's intents as ordered Jira MCP call descriptions (spec 055 R6): `renderBacklog`'s
+ * sibling for the `jira` provider. Each entry is `{ tool, args, why }` — `tool` a bare MCP tool
+ * name, unprefixed (the connector-specific prefix these Atlassian tools carry, and the actual
+ * dispatch, are spec 056's skill's job, not this module's), `args` a plain object, `why` the
+ * human-legible reason (feeds the sync skill's progress note). PURE: no MCP call, no network, no
+ * remote fetch of any kind — this is what keeps `lib/` (and this gate) network-free
+ * (docs/design/board-provider-seam.md invariant 4).
+ *
+ * `config` is `.board.json`'s `jira` sub-object (spec 054); only `statusMap` is consulted.
+ *
+ * The AC-block collapse: the Backlog renderer above issues one command PER acRemove/acAdd/
+ * acCheck/acUncheck entry, because Backlog's AC list has a partial-edit CLI. Jira's marked
+ * description block (docs/board-verbs.md R2) has no partial-edit form — it is replaced
+ * wholesale — so every ac* array here folds into exactly ONE `editJiraIssue` call, whatever the
+ * mix of adds/removes/checks/unchecks. That call's `args` carries the RAW diff, not a
+ * fully-resolved description string: resolving it against the block's CURRENT text needs the
+ * live issue (read via `getJiraIssue`, parsed with `parseSpecPhasesBlock`, the diff applied,
+ * re-rendered with `renderSpecPhasesBlock` — both `lib/board-mirror.mjs`), which needs live data
+ * this pure function neither has nor is allowed to fetch. That resolution is spec 056's skill's
+ * job — this function only describes the diff to make, in order; executing (and resolving) it
+ * is not this module's job.
+ */
+export function renderJira(id, intents, config = {}) {
+  const statusMap = config?.statusMap ?? {};
+  const calls = [];
+
+  if (intents.statusTo) {
+    const target = statusMap[intents.statusTo] ?? intents.statusTo;
+    if (intents.statusTo === "Done" && intents.finalSummary) {
+      // board:final's jira column: comment the summary, THEN transition — so the summary is on
+      // record before the issue moves, mirroring Backlog's combined `-s Done --final-summary`.
+      calls.push({
+        tool: "addOrEditJiraIssueComment",
+        args: { issueIdOrKey: id, commentBody: intents.finalSummary },
+        why: intents.finalSummary,
+      });
+    }
+    calls.push({
+      tool: "transitionJiraIssue",
+      args: { issueIdOrKey: id, status: target },
+      why: `status ${intents.statusFrom} -> ${intents.statusTo}`,
+    });
+  }
+
+  const acChanged = intents.acRemove.length > 0 || intents.acAdd.length > 0
+    || intents.acCheck.length > 0 || intents.acUncheck.length > 0;
+  if (acChanged) {
+    calls.push({
+      tool: "editJiraIssue",
+      args: {
+        issueIdOrKey: id,
+        acRemove: intents.acRemove, acAdd: intents.acAdd,
+        acCheck: intents.acCheck, acUncheck: intents.acUncheck,
+      },
+      why: intents.note ?? "phase ACs reconciled",
+    });
+  }
+
+  if (intents.note) {
+    calls.push({
+      tool: "addOrEditJiraIssueComment",
+      args: { issueIdOrKey: id, commentBody: intents.note },
+      why: intents.note,
+    });
+  }
+
+  return calls;
+}
+
 /**
  * Backward-compatible single-shot planner: `planIntents` then `renderBacklog` in one call.
  * Every call site inside this module now goes through the two halves directly; this wrapper

package/spec-bridge/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,78 @@ 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 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
+ * 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. */
+
+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 +315,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 +362,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 +384,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 }.

package/spec-bridge/lib/gate-runner.mjs

@@ -18,6 +18,14 @@
 //
 // Contract (Claude Code Stop hook): stdin is JSON with { stop_hook_active, session_id, cwd, … };
 // exit 0 = allow the model to stop; exit 2 = block, and stderr becomes the message it sees.
+//
+// Root resolution in evaluate() (spec 062), most specific first: explicit { cwd } option ->
+// $CLAUDE_PROJECT_DIR -> input.cwd -> process.cwd(). An explicit argument is a caller naming a
+// directory on purpose and must never be silently overridden by an ambient variable. The env
+// var still outranks input.cwd: it's the harness's authoritative statement of the project root,
+// while input.cwd is merely where the hook happened to fire (a worktree, a subdir, wherever the
+// session sat). The only production caller, runStopHook below, passes no cwd, so this ordering
+// is byte-identical to before for the real Stop-hook path.
 
 /** Read all of stdin as a string (empty string on a TTY, so it's safe to run by hand). */
 export function readStdin() {
@@ -34,9 +42,9 @@ export function readStdin() {
  * Pure core: given the parsed hook input and the gates, return { block, message }.
  * Separated from process I/O so it is unit-testable.
  */
-export function evaluate(input, gates, { cwd = process.cwd() } = {}) {
+export function evaluate(input, gates, { cwd = undefined } = {}) {
   if (input && input.stop_hook_active === true) return { block: false, message: "", warnings: "" };
-  const start = process.env.CLAUDE_PROJECT_DIR || (input && input.cwd) || cwd;
+  const start = cwd || process.env.CLAUDE_PROJECT_DIR || (input && input.cwd) || process.cwd();
   const ctx = {
     sessionId: (input && input.session_id) || process.env.CLAUDE_CODE_SESSION_ID || null,
     input: input || {},

package/spec-bridge/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) {