rcf-lite 0.0.1 → 0.7.1

package/src/build/formatters/markdown.js

@@ -0,0 +1,406 @@
+// Markdown emitter for the build verb (Phase 6 §D4). Two shapes: the
+// seven-section spec-bundle document (§D3) and the queue-overview
+// table. Zero-dep string assembly, byte-stable given the same result
+// (§D10): no wall clock, no randomness, fixed ordering throughout.
+// British English, ASCII hyphens only (§D17).
+//
+// The bundle's consumer is an implementing agent-harness reading a
+// spec: headings and tables carry the structure without a parser, and
+// the same artefact is human-reviewable as-is (OQ-P6-5).
+
+const SECTION_NUMBERS = {
+  header: 1,
+  queueContext: 2,
+  work: 3,
+  acceptanceCriteria: 4,
+  architecturalContext: 5,
+  testSurface: 6,
+  runbook: 7,
+};
+
+/**
+ * Format a build result as markdown.
+ *
+ * @param {object} result - QueueResult | BundleResult | next-mode empty envelope
+ * @param {('queue'|'bundle'|'next')} mode
+ * @returns {string}
+ */
+export function formatMarkdown(result, mode) {
+  if (mode === 'queue') return formatQueueTable(result);
+  if (mode === 'next' && !result.fbs) return formatNextEmpty(result);
+  return formatBundle(result);
+}
+
+/**
+ * Queue overview as a markdown table.
+ *
+ * @param {object} queue - QueueResult
+ * @returns {string}
+ */
+function formatQueueTable(queue) {
+  const lines = [];
+  const heading = queue.bs
+    ? `# Build queue: ${queue.bs.bsId} - ${queue.bs.title}`
+    : '# Build queue';
+  lines.push(heading, '');
+  if (queue.bs?.generationStrategy) {
+    lines.push(`Generation strategy: ${queue.bs.generationStrategy}`, '');
+  }
+  lines.push('| order | tier | id | title | status | state | blocked by |');
+  lines.push('|---|---|---|---|---|---|---|');
+  for (const item of queue.items) {
+    const state = item.cycle ? 'blocked (cycle)' : item.state;
+    const blockedBy = item.blockedBy.join(', ');
+    const tier = item.tier ?? '-';
+    lines.push(
+      `| ${item.buildOrder} | ${tier} | ${item.fbsId} | ${item.title} | ${item.executionStatus} | ${state} | ${blockedBy} |`,
+    );
+  }
+  const t = queue.totals;
+  lines.push('');
+  lines.push(
+    `Totals: items ${t.items} | notStarted ${t.notStarted} | inProgress ${t.inProgress} `
+      + `| complete ${t.complete} | verified ${t.verified} | actionable ${t.actionable} `
+      + `| blocked ${t.blocked}`,
+  );
+  // Parallel-safe tiers (AC-502-2): items sharing a tier have no
+  // dependency path between them and can be built concurrently.
+  // Cycle-tainted items have no tier and appear in no group.
+  const tiers = queue.tiers ?? [];
+  lines.push('');
+  if (tiers.length > 0) {
+    lines.push('Parallel-safe tiers (items in the same tier have no dependency between them and can build in parallel):');
+    for (const group of tiers) {
+      lines.push(`- tier ${group.tier}: ${group.fbsIds.join(', ')}`);
+    }
+  } else {
+    lines.push('Parallel-safe tiers: none.');
+  }
+  lines.push('');
+  lines.push(`Next actionable: ${queue.nextActionable ?? 'none'}`);
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * `--next` with nothing actionable (§D2 / OQ-P6-2): an explicit
+ * envelope distinguishing "done" from "stuck", not an error.
+ *
+ * @param {object} envelope
+ * @returns {string}
+ */
+function formatNextEmpty(envelope) {
+  const lines = ['# Build queue: nothing actionable', ''];
+  if (envelope.queueEmpty) {
+    lines.push('Queue complete: every item is complete or verified.');
+  } else {
+    const blocked = envelope.blocked.length > 0 ? envelope.blocked.join(', ') : 'none';
+    const inProgress = envelope.inProgress.length > 0 ? envelope.inProgress.join(', ') : 'none';
+    lines.push(
+      'Queue not complete but nothing is actionable.',
+      '',
+      `- Blocked: ${blocked}`,
+      `- In progress: ${inProgress}`,
+    );
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * The seven-section spec bundle (§D3). Section numbering is fixed;
+ * section 5 is omitted entirely when the FBS carries no
+ * contextRequirements (§D11) without renumbering the rest.
+ *
+ * @param {object} bundle - BundleResult
+ * @returns {string}
+ */
+function formatBundle(bundle) {
+  const lines = [];
+  const { fbs } = bundle;
+  lines.push(`# Spec bundle: ${fbs.fbsId} - ${fbs.title}`, '');
+  pushHeader(lines, bundle);
+  pushQueueContext(lines, bundle);
+  pushWork(lines, bundle);
+  pushAcceptanceCriteria(lines, bundle);
+  if (bundle.context) pushArchitecturalContext(lines, bundle);
+  pushTestSurface(lines, bundle);
+  pushRunbook(lines, bundle);
+  return `${lines.join('\n')}\n`;
+}
+
+function pushHeader(lines, bundle) {
+  const { fbs, queue, bs, prd } = bundle;
+  lines.push(`## ${SECTION_NUMBERS.header}. Header`, '');
+  lines.push(`- Item: ${fbs.fbsId} - ${fbs.title}`);
+  lines.push(`- Queue: order ${fbs.buildOrder}, item ${queue.position} of ${queue.total}`);
+  lines.push(`- Execution status: ${fbs.executionStatus}`);
+  if (fbs.estimatedSize !== undefined) lines.push(`- Estimated size: ${fbs.estimatedSize}`);
+  if (fbs.estimatedHours !== undefined) lines.push(`- Estimated hours: ${fbs.estimatedHours}`);
+  if (fbs.riskLevel !== undefined) lines.push(`- Risk level: ${fbs.riskLevel}`);
+  if (fbs.domain !== undefined) lines.push(`- Domain: ${fbs.domain}`);
+  const chain = [];
+  if (bs) chain.push(bs.bsId);
+  if (prd) chain.push(prd.productName ? `${prd.prdId} (${prd.productName})` : prd.prdId);
+  if (chain.length > 0) lines.push(`- Parent chain: ${chain.join(' -> ')}`);
+  if (fbs.updatedAt !== undefined) lines.push(`- Spec last touched: ${fbs.updatedAt}`);
+  lines.push('');
+}
+
+function pushQueueContext(lines, bundle) {
+  const { bs, blockedBy, dependencies, dependents } = bundle;
+  lines.push(`## ${SECTION_NUMBERS.queueContext}. Queue and dependency context`, '');
+  if (blockedBy.length > 0) {
+    const blocking = dependencies
+      .filter((d) => blockedBy.includes(d.fbsId))
+      .map((d) => `${d.fbsId} (${d.executionStatus ?? 'unknown'})`)
+      .join(', ');
+    lines.push(`> **BLOCKED**: unsatisfied dependencies - ${blocking}.`);
+    lines.push('> This bundle is a read-ahead. Do not start implementation until every');
+    lines.push('> dependency is complete or verified; `--strict` refuses this bundle.');
+    lines.push('');
+  }
+  if (bs) {
+    lines.push(`- Build sequence: ${bs.bsId} - ${bs.title}`);
+    if (bs.generationStrategy !== undefined) lines.push(`- Generation strategy: ${bs.generationStrategy}`);
+    if (bs.buildPhilosophy !== undefined) lines.push(`- Build philosophy: ${bs.buildPhilosophy}`);
+    lines.push('');
+  }
+  if (dependencies.length > 0) {
+    lines.push('Dependencies:', '');
+    lines.push('| id | title | status |');
+    lines.push('|---|---|---|');
+    for (const dep of dependencies) {
+      lines.push(`| ${dep.fbsId} | ${dep.title ?? ''} | ${dep.executionStatus ?? ''} |`);
+    }
+    lines.push('');
+  } else {
+    lines.push('Dependencies: none.', '');
+  }
+  lines.push(
+    dependents.length > 0
+      ? `Dependents waiting on this item: ${dependents.join(', ')}`
+      : 'Dependents waiting on this item: none.',
+  );
+  lines.push('');
+}
+
+function pushWork(lines, bundle) {
+  const { fbs } = bundle;
+  lines.push(`## ${SECTION_NUMBERS.work}. The work`, '');
+  lines.push(fbs.summary, '');
+  if (fbs.approach !== undefined) {
+    lines.push('Approach:', '', fbs.approach, '');
+  }
+  if (fbs.deliverables !== undefined && fbs.deliverables.length > 0) {
+    lines.push('Deliverables:', '');
+    for (const d of fbs.deliverables) lines.push(`- ${d}`);
+    lines.push('');
+  }
+  if (fbs.notes !== undefined) {
+    lines.push('Notes:', '', fbs.notes, '');
+  }
+}
+
+function pushAcceptanceCriteria(lines, bundle) {
+  lines.push(`## ${SECTION_NUMBERS.acceptanceCriteria}. Acceptance criteria`, '');
+  for (const us of bundle.userStories) {
+    lines.push(`### ${us.usId}: ${us.title}${us.status !== undefined ? ` (status: ${us.status})` : ''}`, '');
+    if (us.asA !== undefined && us.iWant !== undefined && us.soThat !== undefined) {
+      lines.push(`As a ${us.asA}, I want ${us.iWant}, so that ${us.soThat}.`, '');
+    }
+    const acs = bundle.acceptanceCriteria.filter((ac) => ac.usId === us.usId);
+    const req = bundle.requirements.find((r) => r.reqId === acs[0]?.reqId);
+    if (req) {
+      const meta = [req.category, req.priority !== undefined ? `priority: ${req.priority}` : null]
+        .filter((v) => v !== null && v !== undefined)
+        .join(', ');
+      lines.push(`Parent requirement ${req.reqId}: ${req.title}${meta ? ` (${meta})` : ''}`, '');
+      if (req.description !== undefined) lines.push(`> ${req.description}`);
+      if (req.rationale !== undefined) {
+        if (req.description !== undefined) lines.push('>');
+        lines.push(`> Rationale: ${req.rationale}`);
+      }
+      if (req.description !== undefined || req.rationale !== undefined) lines.push('');
+    }
+    for (const ac of acs) {
+      lines.push(`#### ${ac.id}: ${ac.description}`, '');
+      if (ac.given !== undefined) lines.push(`- Given: ${ac.given}`);
+      if (ac.when !== undefined) lines.push(`- When: ${ac.when}`);
+      if (ac.then !== undefined) lines.push(`- Then: ${ac.then}`);
+      lines.push(`- Testable: ${ac.testable ? 'yes' : 'no'}`);
+      lines.push('');
+    }
+  }
+}
+
+/**
+ * Render a resolved TAD / PRD section value. String content renders as
+ * prose; structured content (the TAD's sections are objects / arrays)
+ * renders as a fenced JSON block - still byte-stable, still readable.
+ */
+function pushSectionValue(lines, value) {
+  if (typeof value === 'string') {
+    lines.push(value, '');
+  } else {
+    lines.push('```json');
+    lines.push(JSON.stringify(value, null, 2));
+    lines.push('```', '');
+  }
+}
+
+function pushArchitecturalContext(lines, bundle) {
+  const ctx = bundle.context;
+  lines.push(`## ${SECTION_NUMBERS.architecturalContext}. Architectural context`, '');
+  for (const tac of ctx.tacs) {
+    lines.push(`### TAC ${tac.tacId}: ${tac.name}`, '');
+    if (tac.purpose !== undefined) lines.push(`Purpose: ${tac.purpose}`, '');
+    if (tac.responsibilities !== undefined && tac.responsibilities.length > 0) {
+      lines.push('Responsibilities:', '');
+      for (const r of tac.responsibilities) lines.push(`- ${r}`);
+      lines.push('');
+    }
+    if (tac.interfaces !== undefined && tac.interfaces.length > 0) {
+      lines.push('Interfaces:', '');
+      for (const i of tac.interfaces) {
+        const kind = i.kind !== undefined ? ` (${i.kind})` : '';
+        const desc = i.description !== undefined ? `: ${i.description}` : '';
+        lines.push(`- ${i.name}${kind}${desc}`);
+      }
+      lines.push('');
+    }
+    if (tac.dependencies !== undefined && tac.dependencies.length > 0) {
+      lines.push('Dependencies:', '');
+      for (const d of tac.dependencies) {
+        const ref = d.kind === 'tac' && d.tacId !== undefined ? `${d.kind} ${d.tacId}` : d.kind;
+        const desc = d.description !== undefined ? `: ${d.description}` : '';
+        lines.push(`- ${d.name} (${ref})${desc}`);
+      }
+      lines.push('');
+    }
+    if (tac.tradeoffs !== undefined) lines.push(`Tradeoffs: ${tac.tradeoffs}`, '');
+    if (tac.notes !== undefined) lines.push(`Notes: ${tac.notes}`, '');
+  }
+  for (const adr of ctx.adrs) {
+    lines.push(`### ADR ${adr.adrId}: ${adr.title}${adr.status !== undefined ? ` (${adr.status})` : ''}`, '');
+    if (adr.context !== undefined) lines.push(`Context: ${adr.context}`, '');
+    if (adr.decision !== undefined) lines.push(`Decision: ${adr.decision}`, '');
+    if (adr.consequences !== undefined) lines.push(`Consequences: ${adr.consequences}`, '');
+    if (adr.alternativesConsidered !== undefined && adr.alternativesConsidered.length > 0) {
+      lines.push('Alternatives considered:', '');
+      for (const alt of adr.alternativesConsidered) {
+        const summary = alt.summary !== undefined ? `: ${alt.summary}` : '';
+        const reason = alt.reasonNotChosen !== undefined ? ` (not chosen: ${alt.reasonNotChosen})` : '';
+        lines.push(`- ${alt.name}${summary}${reason}`);
+      }
+      lines.push('');
+    }
+  }
+  for (const [name, value] of Object.entries(ctx.tadSections)) {
+    lines.push(`### TAD section: ${name}`, '');
+    pushSectionValue(lines, value);
+  }
+  for (const [name, value] of Object.entries(ctx.prdSections)) {
+    lines.push(`### PRD section: ${name}`, '');
+    pushSectionValue(lines, value);
+  }
+  if (ctx.unresolvedSections.length > 0) {
+    lines.push(
+      `Warning - unresolved sections (names that did not match a top-level TAD / PRD property): ${ctx.unresolvedSections.join(', ')}`,
+      '',
+    );
+  }
+  const pt = ctx.passThrough;
+  const ptRows = [
+    ['Existing modules', pt.existingModules],
+    ['Schemas', pt.schemas],
+    ['External docs', pt.externalDocs],
+    ['Other', pt.other],
+  ].filter(([, list]) => list.length > 0);
+  if (ptRows.length > 0) {
+    lines.push('Referenced material (pass-through, verbatim):', '');
+    for (const [label, list] of ptRows) {
+      lines.push(`- ${label}: ${list.join(', ')}`);
+    }
+    lines.push('');
+  }
+}
+
+function pushTestSurface(lines, bundle) {
+  lines.push(`## ${SECTION_NUMBERS.testSurface}. Existing test surface`, '');
+  lines.push('Presence reporting off the tree, not a coverage verdict (`rcf coverage` is the coverage surface).', '');
+  for (const entry of bundle.tests) {
+    if (!entry.covered && entry.suites.length === 0) {
+      lines.push(`- ${entry.acId}: no existing tests - test suite to be written for this AC`);
+      continue;
+    }
+    const suites = entry.suites.length > 0 ? entry.suites.join(', ') : 'none';
+    lines.push(`- ${entry.acId}: suites: ${suites}`);
+    for (const c of entry.cases) {
+      const pointer = c.testPointer !== undefined ? ` [${c.testPointer}]` : '';
+      const status = c.status !== undefined ? ` (${c.status})` : '';
+      lines.push(`  - ${c.tcId}${status}: ${c.description ?? ''}${pointer}`);
+    }
+  }
+  lines.push('');
+}
+
+/**
+ * Section 7 - the full RCF five-stage build-cycle runbook (§D3.7,
+ * amendment D3-A). Static text parameterised only by fbsId and the
+ * in-scope AC ids; the each-stage-commits discipline is part of the
+ * printed contract. The tool assembles and referees; the harness
+ * executes the cycle.
+ */
+function pushRunbook(lines, bundle) {
+  const fbsId = bundle.fbs.fbsId;
+  const acIds = bundle.acceptanceCriteria.map((ac) => ac.id).join(', ');
+  lines.push(`## ${SECTION_NUMBERS.runbook}. Build-cycle runbook`, '');
+  lines.push('This bundle is the work order for one pass of the RCF five-stage build');
+  lines.push('cycle: Define -> Build -> Review -> Test -> Finalise. The tool assembles');
+  lines.push('and referees; the harness executes. Every stage ends in a commit.', '');
+  // Deep-layer pointer (Phase 7.5 §D5.4, OQ-P7.5-3): the runbook is the
+  // terse just-in-time layer; the playbook is the deep layer.
+  lines.push('Deep guidance: rcf://docs/build-cycle and the rcf_execute_build_cycle prompt, or `rcf guidance build-cycle-playbook` on the CLI.', '');
+
+  lines.push('### Stage 1 - Define', '');
+  lines.push('Satisfied by this bundle: the FBS, acceptance criteria, ancestry and');
+  lines.push('architectural context above ARE the definition. Confirm your plan against');
+  lines.push(`every in-scope acceptance criterion (${acIds}) in section 4 before writing`);
+  lines.push('code, then mark pickup:', '');
+  lines.push(`    rcf build ${fbsId} --mark inProgress`, '');
+  lines.push('Commit any plan artefacts the driving workflow requires.', '');
+
+  lines.push('### Stage 2 - Build', '');
+  lines.push('Implement to the acceptance criteria in section 4 using the architectural');
+  lines.push('context in section 5. The bundle is the spec: deviation is escalation to');
+  lines.push('the operator of the loop, not improvisation. As you implement, author or');
+  lines.push('update Code Nodes for the source you write:', '');
+  lines.push('    rcf create cn --path <file>[#symbol] --acs <ac-ids>', '');
+  lines.push('Do this now, not as an afterthought: comprehension of which symbols serve');
+  lines.push('which acceptance criteria is cheapest to capture while you are writing the');
+  lines.push('code, and Stage 5 refuses completion without it. Commit at stage end.', '');
+
+  lines.push('### Stage 3 - Review', '');
+  lines.push('Mechanical referee pass:', '');
+  lines.push('    rcf validate', '');
+  lines.push('must come back clean; then re-read the diff against every in-scope');
+  lines.push('acceptance criterion and document any deviations. Commit.', '');
+
+  lines.push('### Stage 4 - Test', '');
+  lines.push('Exercise every in-scope acceptance criterion: write or extend the TS / TC');
+  lines.push('documents (section 6 lists the existing surface and the flagged gaps) and');
+  lines.push('the tests they point to, until:', '');
+  lines.push('    rcf coverage --strict', '');
+  lines.push('covers the in-scope acceptance criteria. Commit.', '');
+
+  lines.push('### Stage 5 - Finalise', '');
+  lines.push('CI green; PR raised and merged per the driving workflow\'s convention.');
+  lines.push('After the merge:', '');
+  lines.push(`    rcf build ${fbsId} --mark complete`, '');
+  lines.push('This refuses (exit 3, missingCodeNodes) if any in-scope acceptance');
+  lines.push('criterion still carries no Code Node - go back to Stage 2 and author it,');
+  lines.push('or, for a genuinely no-code spec (docs-only, config-only), declare:', '');
+  lines.push(`    rcf build ${fbsId} --mark complete --no-code-nodes`, '');
+  lines.push('Then ship-gate the deployed app - an independent rcf-verify run that');
+  lines.push('passes with ship authority promotes complete -> verified:', '');
+  lines.push(`    rcf finalise ${fbsId} --url <deploy-url>`);
+}

package/src/build/index.js

@@ -0,0 +1,14 @@
+// Public surface for the build module (Phase 6 §D8). Pure logic +
+// formatters; the CLI handler lives at `src/cli/build.js`.
+
+export { computeQueue, selectNext, byBuildOrder, LIFECYCLE } from './queue.js';
+export { assembleBundle } from './bundle.js';
+export {
+  checkCodeNodeGate,
+  checkContrastBeforePaletteGate,
+  checkDesignGate,
+  hasNoCodeNodesDeclaration,
+  planMark,
+} from './mark.js';
+export { formatMarkdown } from './formatters/markdown.js';
+export { formatJson } from './formatters/json.js';

package/src/build/mark.js

@@ -0,0 +1,177 @@
+// Lifecycle marking (Phase 6 §D5). Pure transition planning for
+// `rcf build <fbs-id> --mark <status>`: enum validation, forward-only
+// transition-table validation, idempotent no-op detection. Returns a
+// plan (or a structured error / refusal); the CLI handler executes the
+// plan via the Phase 4 `updateDocument` write path. Phase 6 adds no
+// new write primitive.
+//
+// The lifecycle is the schema enum, in order:
+//   notStarted -> inProgress -> complete -> verified
+// Forward jumps are legal (notStarted -> complete for trivially-shipped
+// items) but the mark ladder caps at `complete`: `--mark verified` is
+// refused (exit 4) and points to the finalise gate (`rcf finalise`), which
+// is the only path that writes `verified` after an independent verify run.
+// Backward transitions are refused (exit 4) and the message names the
+// deliberate-correction escape hatch (`rcf update`).
+
+import { rcfError } from '#core/errors';
+import { LIFECYCLE } from './queue.js';
+
+// Phase 10 (X2 CodeNode bridge, D17, operator ruling 2026-07-10): the
+// mark-complete CN gate. The no-code-nodes declaration is a dedicated
+// `noCodeNodes: boolean` field on the FBS schema (rcf-schemas@0.3.1) - NOT
+// a free-form convention string. An unvalidated magic value would silently
+// fail on a typo, which is exactly the failure mode this feature exists to
+// make visible (operator ruling 2026-07-10).
+/**
+ * True when the FBS already carries the `--no-code-nodes` declaration.
+ * @param {object} fbs
+ * @returns {boolean}
+ */
+export function hasNoCodeNodesDeclaration(fbs) {
+  return fbs?.noCodeNodes === true;
+}
+
+/**
+ * @typedef {object} MarkPlan
+ * @property {string} fbsId
+ * @property {string} from
+ * @property {string} to
+ * @property {boolean} noOp - true when the item is already at `to`
+ * @property {boolean} [refused] - true on a backward transition
+ * @property {string} [message] - refusal message (refused plans only)
+ */
+
+/**
+ * Plan a lifecycle transition. Returns an RcfError (usage) for a bad
+ * status value or a non-FBS id, a refused plan for a backward
+ * transition, otherwise an executable plan.
+ *
+ * @param {import('#core/store/walker.js').TreeModel} tree
+ * @param {object} opts
+ * @param {string} opts.fbsId
+ * @param {string} opts.status - target executionStatus
+ * @returns {MarkPlan | import('#core/errors').RcfError}
+ */
+export function planMark(tree, { fbsId, status }) {
+  if (!LIFECYCLE.includes(status)) {
+    return rcfError({
+      kind: 'usage',
+      message: `build: unknown --mark value '${status}' (expected ${LIFECYCLE.join(' | ')})`,
+    });
+  }
+  const fbs = tree.byId.get(fbsId);
+  if (!fbs || tree.kindById.get(fbsId) !== 'fbs') {
+    return rcfError({
+      kind: 'usage',
+      message: `build: id ${fbsId} not found or not an FBS`,
+      documentId: fbsId,
+    });
+  }
+  const from = fbs.executionStatus;
+  // The mark ladder caps at `complete` (w-2026-07-22-004). `verified` means
+  // "independently verified against the running deploy" - it is written only by
+  // the finalise gate (`rcf finalise`), which spawns a fresh rcf-verify run.
+  // Letting `--mark verified` promote with no verify run would let the builder
+  // sidestep that gate with one flag, defeating the spec-9 independence
+  // guarantee. Refused as part of the mark-refusal family (exit 4); the message
+  // names the finalise gate and keeps `rcf update` as the explicit manual
+  // override (unchanged - a deliberate, logged operator decision).
+  if (status === 'verified') {
+    return {
+      fbsId,
+      from,
+      to: status,
+      noOp: false,
+      refused: true,
+      message: `build: refusing --mark verified on ${fbsId}; 'verified' is written only by the `
+        + `independent verify gate, not by --mark. Promote it with: rcf finalise ${fbsId} --url <deploy-url>. `
+        + `For a deliberate manual override (no verify run) use: rcf update ${fbsId} --set executionStatus=verified`,
+    };
+  }
+  const fromIndex = LIFECYCLE.indexOf(from);
+  const toIndex = LIFECYCLE.indexOf(status);
+  if (toIndex === fromIndex) {
+    return { fbsId, from, to: status, noOp: true };
+  }
+  if (toIndex < fromIndex) {
+    return {
+      fbsId,
+      from,
+      to: status,
+      noOp: false,
+      refused: true,
+      message: `build: refusing backward transition ${from} -> ${status} on ${fbsId}; `
+        + `for a deliberate correction use: rcf update ${fbsId} --set executionStatus=${status}`,
+    };
+  }
+  return { fbsId, from, to: status, noOp: false };
+}
+
+/**
+ * The mark-complete CN gate (D17). Deterministic edge counting: an AC is
+ * "covered" when `tree.cnByAcId` carries at least one implementing CN.
+ * Called only when the target status is `complete`; the caller (cli/build)
+ * skips this entirely when the FBS already carries the no-code-nodes
+ * declaration or the invocation supplies `--no-code-nodes`.
+ *
+ * @param {import('#core/store/walker.js').TreeModel} tree
+ * @param {object} fbs - the FBS document being marked complete
+ * @returns {{ ok: true } | { ok: false, missingAcIds: string[] }}
+ */
+export function checkCodeNodeGate(tree, fbs) {
+  const missingAcIds = (fbs.acIds ?? []).filter((acId) => (tree.cnByAcId?.get(acId) ?? []).length === 0);
+  if (missingAcIds.length === 0) return { ok: true };
+  return { ok: false, missingAcIds: [...missingAcIds].sort() };
+}
+
+// Track B (ui-design-gate-0.7.0-spec §5.2, §5.5): the `--mark complete`
+// design gate. Refuses when the FBS is uiBearing=true and
+// designStageComplete is not true on the FBS record. The gate is the
+// boolean primitive per §12 O-3 (Decided); the executionStatus enum is
+// unchanged.
+/**
+ * @param {object} fbs
+ * @returns {{ ok: true } | { ok: false, reason: 'designStageIncomplete' }}
+ */
+export function checkDesignGate(fbs) {
+  if (fbs?.uiBearing !== true) return { ok: true };
+  if (fbs?.designStageComplete === true) return { ok: true };
+  return { ok: false, reason: 'designStageIncomplete' };
+}
+
+// Track B (ui-design-gate-0.7.0-spec §7 mandate 10). Refuses when the
+// operator's own attestation says the wrong order was authored, and
+// (optionally) when a git-history probe unambiguously contradicts the
+// operator's attestation. The git probe is out of scope for the pure
+// mark.js module; the caller (cli/build) supplies the probe result.
+/**
+ * @param {object} fbs
+ * @param {object} [historyProbe]  optional git-history corroboration result
+ * @param {boolean} [historyProbe.inconclusive]  true when git says nothing
+ * @param {boolean} [historyProbe.tokensCreatedFirst] true when history says tokens preceded contrast test
+ * @returns {{ ok: true } | { ok: false, reason: string, message: string }}
+ */
+export function checkContrastBeforePaletteGate(fbs, historyProbe = { inconclusive: true }) {
+  if (fbs?.uiBearing !== true) return { ok: true };
+  const stage = fbs?.designStage;
+  if (!stage?.themeAndA11y) return { ok: true }; // gate deferred to design-mark-complete surface
+  const boolean = stage.themeAndA11y.contrastTestAuthoredBeforePalette;
+  if (boolean === false) {
+    return {
+      ok: false,
+      reason: 'contrastTestAfterPalette',
+      message: `build --mark complete: refused - ${fbs.fbsId} designStage.themeAndA11y.contrastTestAuthoredBeforePalette is false. `
+        + 'Author the contrast test before the palette, or record the reversal by ratifying the ordering explicitly.',
+    };
+  }
+  if (boolean === true && historyProbe && historyProbe.inconclusive !== true && historyProbe.tokensCreatedFirst === true) {
+    return {
+      ok: false,
+      reason: 'contrastGitHistoryConflict',
+      message: `build --mark complete: refused - ${fbs.fbsId} attests contrastTestAuthoredBeforePalette=true, but git history shows the tokens module (${stage.themeAndA11y.themeTokensModule}) was created before the contrast test (${stage.themeAndA11y.contrastTestPath}). `
+        + 'Reconcile the attestation with the history: rewrite the test-authoring order in the log, or set contrastTestAuthoredBeforePalette=false and accept the ruling.',
+    };
+  }
+  return { ok: true };
+}