rcf-lite 0.28.4 → 0.29.0

package/src/query/gates.js

@@ -45,7 +45,7 @@
 
 import { computeQueue } from '../build/queue.js';
 import { isOptedOut } from '../req-baseline/opt-out.js';
-import { BRIEF_KINDS } from '../define/ledgers.js';
+import { BRIEF_KINDS, parseResolvedBy } from '../define/ledgers.js';
 
 /** Canonical stage order (proposal §3.2). */
 export const STAGE_ORDER = /** @type {const} */ (['D1', 'D2', 'D3', 'D4', 'D5', 'D6', 'D7', 'D8']);
@@ -91,6 +91,195 @@ export const INTERFACE_KINDS = /** @type {const} */ ([
   'port', 'fileFormat', 'fixture', 'other',
 ]);
 
+/**
+ * Owning persona for every stage-gate check in 0.29.0 (ADR-4126).
+ *
+ * Two values: `productOwner` (the person who owns what the product
+ * must do) and `engineer` (the person who owns how it is built).
+ * There is no `either` / `shared` / `both`; a check that would need
+ * both is split, which is what happens to `skeleton:reqFields`
+ * (becomes `skeleton:reqIntent` + `skeleton:reqShape`) and
+ * `decisions:allAnswered` (becomes `decisions:wellFormed` +
+ * `decisions:allAnswered`). A failing item inherits its check's
+ * persona; there is no per-item override.
+ *
+ * The `notApplicable` placeholder (`stage:<D>:scope`) carries the
+ * per-stage fallback persona from `STAGE_FALLBACK_PERSONA` below.
+ * It is always ok so it never affects a level verdict.
+ */
+export const CHECK_PERSONA = /** @type {const} */ ({
+  // D1 Brief: every check is PO (the brief is the PO's statement of intent).
+  'brief:sinceFreeze': 'productOwner',
+  'brief:kinds': 'productOwner',
+  'brief:openQuestions': 'productOwner',
+  'brief:profile': 'productOwner',
+  // D2 Skeleton: resolvedBy + reqIntent are PO; reqShape, tadPersistence, deployAdr are engineer.
+  'skeleton:resolvedBy': 'productOwner',
+  'skeleton:reqIntent': 'productOwner',
+  'skeleton:reqShape': 'engineer',
+  'skeleton:tadPersistence': 'engineer',
+  'skeleton:deployAdr': 'engineer',
+  // D3 Shapes: every check is engineer (shapes are the engineer's first act after hand-over).
+  'shapes:tacHasInterface': 'engineer',
+  'shapes:kindVocabulary': 'engineer',
+  'shapes:draftSettled': 'engineer',
+  // D4 Stories: reqHasUs is PO ("what does someone do with this?"); the floors are engineer.
+  'stories:reqHasUs': 'productOwner',
+  'stories:usFloors': 'engineer',
+  // D5 Crosscut: TAD + concern-ledger content is engineering.
+  'crosscut:securityArchitecture': 'engineer',
+  'crosscut:operationalConcerns': 'engineer',
+  'crosscut:concernsResolved': 'engineer',
+  // D6 Consistency: schema validity and probes are engineer.
+  'consistency:validateClean': 'engineer',
+  'consistency:probeCount': 'engineer',
+  // D7 Decisions: enumeration is PO (the PO answers or lets the default stand);
+  // zero-open is the engineer's hand-over condition.
+  'decisions:wellFormed': 'productOwner',
+  'decisions:allAnswered': 'engineer',
+  // D8 Freeze: every check is mechanical / engineering.
+  'freeze:priorGates': 'engineer',
+  'freeze:acFbsOwnership': 'engineer',
+  'freeze:queueHead': 'engineer',
+  'freeze:validateClean': 'engineer',
+});
+
+/**
+ * Per-check heading question in the owning persona's register
+ * (ADR-4126, proposal section 1.1). The text report and the
+ * Readiness tab print the question as the heading of each check's
+ * findings list. Static per check in 0.29.0; per-item plain-English
+ * wording is step 3's guided elicitation.
+ */
+export const CHECK_QUESTION = /** @type {const} */ ({
+  'brief:sinceFreeze': 'What has changed, or what is this project for?',
+  'brief:kinds': 'Is this a capability, a constraint, an actor, or something else?',
+  'brief:openQuestions': 'Any open questions in the brief, resolved or promoted to a decision?',
+  'brief:profile': 'How do you want to review, and who are you writing for?',
+  'skeleton:resolvedBy': 'Does this statement become a requirement, an entity, or an omission?',
+  'skeleton:reqIntent': 'What does this requirement mean and where does it sit?',
+  'skeleton:reqShape': 'Every requirement in scope carries a shape classification.',
+  'skeleton:tadPersistence': 'TAD data architecture lists dataStores and coreEntities for persistence REQs.',
+  'skeleton:deployAdr': 'Exactly one Deploy target or Deploy deferral ADR exists.',
+  'shapes:tacHasInterface': 'Every TAC in scope has at least one interface.',
+  'shapes:kindVocabulary': 'Every interface kind is in the closed vocabulary.',
+  'shapes:draftSettled': 'Every draft interface has been settled (the [draft] marker is removed).',
+  'stories:reqHasUs': 'What does someone do with this requirement?',
+  'stories:usFloors': 'Every story in scope meets the class, tacIds and testability floors.',
+  'crosscut:securityArchitecture': 'TAD.securityArchitecture is present when an auth or httpApi REQ exists.',
+  'crosscut:operationalConcerns': 'TAD.operationalConcerns is present when a deployed-scope AC exists.',
+  'crosscut:concernsResolved': 'Every concern-ledger entry on a REQ in scope is applied or waived.',
+  'consistency:validateClean': 'Validate is clean tree-wide.',
+  'consistency:probeCount': 'Zero open probe-ledger entries.',
+  'decisions:wellFormed': 'Every decision is enumerated (question, two or more options, a default).',
+  'decisions:allAnswered': 'Zero decisions are open.',
+  'freeze:priorGates': 'Every prior stage passed or is acknowledged at the current hash.',
+  'freeze:acFbsOwnership': 'Every AC is owned by exactly one FBS.',
+  'freeze:queueHead': 'Queue head is actionable and not a placeholder.',
+  'freeze:validateClean': 'Validate is clean tree-wide.',
+});
+
+/**
+ * Per-stage fallback persona for the `stage:<D>:scope` placeholder
+ * check that `notApplicable` envelopes carry. The placeholder is
+ * always ok so this never affects a level, but keeps "every check
+ * has a persona" true for consumers and the table test (ADR-4126
+ * decision 10).
+ */
+export const STAGE_FALLBACK_PERSONA = /** @type {const} */ ({
+  D1: 'productOwner',
+  D2: 'productOwner',
+  D3: 'engineer',
+  D4: 'productOwner',
+  D5: 'engineer',
+  D6: 'engineer',
+  D7: 'productOwner',
+  D8: 'engineer',
+});
+
+/**
+ * Look up the question heading for a check name.
+ * @param {string} name
+ * @returns {string}
+ */
+export function checkQuestion(name) {
+  return /** @type {any} */ (CHECK_QUESTION)[name] ?? '';
+}
+
+/**
+ * Look up the owning persona for a check name.
+ * @param {string} name
+ * @returns {'productOwner' | 'engineer' | null}
+ */
+export function checkPersona(name) {
+  const v = /** @type {any} */ (CHECK_PERSONA)[name];
+  return v === 'productOwner' || v === 'engineer' ? v : null;
+}
+
+/**
+ * Draft marker (ADR-4126 for `TAC.interfaces[].description` in 0.29.0;
+ * REQ-188 extends it to `TAC.purpose` and `coreEntities[].description`
+ * in 0.30.0). A description that starts with `[draft]` after optional
+ * leading whitespace is pre-populated engineer entry material; the
+ * engineer removes the marker when the shape is settled. Decision 6
+ * uses the same bracket-prefix convention for AC class.
+ */
+const INTERFACE_DRAFT_RE = /^\[draft\]/;
+
+/**
+ * True when a string carries the leading `[draft]` marker
+ * (whitespace tolerated). Pure string test used by every draft-home
+ * reader below.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function hasDraftMarker(value) {
+  if (typeof value !== 'string') return false;
+  return INTERFACE_DRAFT_RE.test(value.trimStart());
+}
+
+/**
+ * True when an interface's `description` carries the leading
+ * `[draft]` marker (whitespace tolerated). Thin wrapper over
+ * `hasDraftMarker` kept for ADR-4126 call sites; REQ-188 adds
+ * `parseTacPurposeDraft` and `parseCoreEntityDraft` for the two new
+ * homes.
+ *
+ * @param {unknown} iface
+ * @returns {boolean}
+ */
+export function parseInterfaceDraft(iface) {
+  if (!iface || typeof iface !== 'object') return false;
+  return hasDraftMarker(/** @type {any} */ (iface).description);
+}
+
+/**
+ * True when a TAC's `purpose` carries the leading `[draft]` marker
+ * (whitespace tolerated). REQ-188 draft home; the engineer removes
+ * the marker when the TAC's purpose is owned.
+ *
+ * @param {unknown} tac
+ * @returns {boolean}
+ */
+export function parseTacPurposeDraft(tac) {
+  if (!tac || typeof tac !== 'object') return false;
+  return hasDraftMarker(/** @type {any} */ (tac).purpose);
+}
+
+/**
+ * True when a coreEntities entry's `description` carries the
+ * leading `[draft]` marker (whitespace tolerated). REQ-188 draft
+ * home; the engineer removes the marker when the entity is owned.
+ *
+ * @param {unknown} entity
+ * @returns {boolean}
+ */
+export function parseCoreEntityDraft(entity) {
+  if (!entity || typeof entity !== 'object') return false;
+  return hasDraftMarker(/** @type {any} */ (entity).description);
+}
+
 /** Warn-with-ack stages in 0.29.0 (ADR-4122). */
 const WARN_WITH_ACK = new Set(['D3', 'D5', 'D6']);
 
@@ -156,12 +345,26 @@ export function parseAcClass(ac) {
  *   twentieth failure. `ok` is likewise derived from the untruncated
  *   count. The section 2.4 shape stays intact -- `failing` remains the
  *   display array; no new field is exported.
- * @returns {{ name: string, ok: boolean, over: 'delta'|'tree', pass: number, total: number, failing: Array<{ id: string, why: string }> }}
+ * @returns {{ name: string, ok: boolean, over: 'delta'|'tree', pass: number, total: number, failing: Array<{ id: string, why: string }>, persona: 'productOwner'|'engineer', question: string }}
  */
 function makeCheck(name, over, total, failing, totalFailingCount) {
   const nFailing = typeof totalFailingCount === 'number' ? totalFailingCount : failing.length;
   const pass = Math.max(0, total - nFailing);
-  return { name, ok: nFailing === 0, over, pass, total, failing: [...failing] };
+  // Resolve persona + question for the check. For stage placeholders
+  // (`stage:<D>:scope`) the persona comes from STAGE_FALLBACK_PERSONA.
+  // Unknown names fall back to engineer with an empty question so
+  // consumers never see null; the table test catches any new check
+  // that forgets to register in CHECK_PERSONA / CHECK_QUESTION.
+  let persona = /** @type {any} */ (CHECK_PERSONA)[name];
+  if (!persona) {
+    const stageMatch = /^stage:(D[1-8]):scope$/.exec(name);
+    persona = stageMatch
+      ? /** @type {any} */ (STAGE_FALLBACK_PERSONA)[stageMatch[1]]
+      : 'engineer';
+  }
+  const question = /** @type {any} */ (CHECK_QUESTION)[name]
+    ?? (name.startsWith('stage:') ? 'No documents of this stage’s type are in scope.' : '');
+  return { name, ok: nFailing === 0, over, pass, total, failing: [...failing], persona, question };
 }
 
 /**
@@ -342,57 +545,68 @@ export function checkD2Skeleton(ctx) {
 
   const checks = [];
 
-  // Check 1: every capability/constraint/entity/... statement resolves
-  // (the statement carries `resolvedBy` naming a REQ / TAD entity / TAC
-  // / recorded omission id, OR its text matches an existing REQ title).
-  // Cheap check: a `resolvedBy` string or a name-hit on titles.
-  const resolvedByStmt = (s) => {
+  // Check 1 (0.30.0): every capability/constraint/entity/... statement
+  // resolves to a closed-grammar pointer in `resolvedBy`:
+  //   REQ-nnn | TAD.entity:<name> | PRD.user:<name>
+  //   | TAD.system:<name> | TAC-nnnn | omitted:<reason>
+  // The 0.29.0 REQ-title fallback is dropped (decision 3; a title hit
+  // becomes a suggestion the PR 2 computeQuestions surface returns).
+  // A statement with no `resolvedBy` fails; a statement with a
+  // `resolvedBy` outside the grammar fails with 'pointer does not
+  // resolve'.
+  /** @type {Array<{ id: string, why: string }>} */
+  const unresolvedFailing = [];
+  for (const s of resolvingStmts) {
     const rb = s?.resolvedBy;
-    if (typeof rb === 'string' && rb.length > 0) return true;
-    if (rb && typeof rb === 'object' && Object.keys(rb).length > 0) return true;
-    const text = typeof s?.text === 'string' ? s.text.trim().toLowerCase() : '';
-    if (!text) return false;
-    for (const req of tree.requirements ?? []) {
-      const title = typeof req?.title === 'string' ? req.title.toLowerCase() : '';
-      if (title && text.includes(title)) return true;
+    if (typeof rb !== 'string' || rb.length === 0) {
+      unresolvedFailing.push({ id: `brief:${s.id}`, why: `${s.kind} statement has no resolvedBy` });
+      continue;
     }
-    return false;
-  };
-  const unresolvedStmts = resolvingStmts.filter((s) => !resolvedByStmt(s));
+    const parsed = parseResolvedBy(rb, tree);
+    if (!parsed.ok) {
+      unresolvedFailing.push({ id: `brief:${s.id}`, why: 'pointer does not resolve' });
+    }
+  }
   checks.push(makeCheck(
     'skeleton:resolvedBy',
     'delta',
     resolvingStmts.length,
-    unresolvedStmts.map((s) => ({ id: `brief:${s.id}`, why: `${s.kind} statement has no resolvedBy and no REQ-title hit` })),
+    unresolvedFailing,
   ));
 
-  // Check 2: every REQ in scope has description, shapeClassification, domain.
+  // Checks 2a / 2b: the former `skeleton:reqFields` split into two
+  // homogeneous checks (ADR-4126, proposal section 1.3). Each
+  // evaluates every REQ in scope independently so a REQ with a TODO
+  // description still has its shapes reported, and vice versa.
+  const reqIntentFail = [];
   const reqShapeFail = [];
   for (const req of reqInScope) {
+    // reqIntent (productOwner): description without a TODO + domain
+    // (what the requirement means and where it sits).
     if (typeof req.description !== 'string' || req.description.length === 0 || TODO_RE.test(req.description)) {
-      reqShapeFail.push({ id: req.reqId, why: 'description missing or contains TODO placeholder' });
-      continue;
+      reqIntentFail.push({ id: req.reqId, why: 'description missing or contains TODO placeholder' });
+    } else if (typeof req.domain !== 'string' || req.domain.length === 0) {
+      reqIntentFail.push({ id: req.reqId, why: 'domain missing' });
     }
+    // reqShape (engineer): shapeClassification.shapes classification.
     if (!req.shapeClassification || !Array.isArray(req.shapeClassification.shapes)) {
       reqShapeFail.push({ id: req.reqId, why: 'shapeClassification.shapes missing' });
-      continue;
-    }
-    if (typeof req.domain !== 'string' || req.domain.length === 0) {
-      reqShapeFail.push({ id: req.reqId, why: 'domain missing' });
     }
   }
-  checks.push(makeCheck('skeleton:reqFields', 'delta', reqInScope.length, reqShapeFail));
+  checks.push(makeCheck('skeleton:reqIntent', 'delta', reqInScope.length, reqIntentFail));
+  checks.push(makeCheck('skeleton:reqShape', 'delta', reqInScope.length, reqShapeFail));
 
-  // Check 3: TAD.dataStores + coreEntities present when any persistence
+  // Check 3: TAD.dataArchitecture.dataStores + coreEntities present when any
   // REQ exists tree-wide.
   const persistenceReq = (tree.requirements ?? []).some((r) => Array.isArray(r?.shapeClassification?.shapes) && r.shapeClassification.shapes.includes('persistence'));
   const tadFail = [];
   if (persistenceReq) {
     const tad = tree.tad ?? {};
-    const dataStores = Array.isArray(tad.dataStores) ? tad.dataStores : [];
-    const coreEntities = Array.isArray(tad.coreEntities) ? tad.coreEntities : [];
-    if (dataStores.length === 0) tadFail.push({ id: 'TAD.dataStores', why: 'TAD.dataStores empty while persistence REQ exists' });
-    if (coreEntities.length === 0) tadFail.push({ id: 'TAD.coreEntities', why: 'TAD.coreEntities empty while persistence REQ exists' });
+    const dataArch = tad?.dataArchitecture ?? {};
+    const dataStores = Array.isArray(dataArch.dataStores) ? dataArch.dataStores : [];
+    const coreEntities = Array.isArray(dataArch.coreEntities) ? dataArch.coreEntities : [];
+    if (dataStores.length === 0) tadFail.push({ id: 'TAD.dataArchitecture.dataStores', why: 'TAD.dataArchitecture.dataStores empty while persistence REQ exists' });
+    if (coreEntities.length === 0) tadFail.push({ id: 'TAD.dataArchitecture.coreEntities', why: 'TAD.dataArchitecture.coreEntities empty while persistence REQ exists' });
   }
   checks.push(makeCheck('skeleton:tadPersistence', 'tree', persistenceReq ? 2 : 0, tadFail));
 
@@ -421,14 +635,20 @@ export function checkD2Skeleton(ctx) {
 const INTERFACE_KINDS_SET = new Set(INTERFACE_KINDS);
 
 /**
- * D3 -- Interface contracts and shapes. 0.29.0 runs only the cheap
- * presence + closed-vocabulary checks.
+ * D3 -- Interface contracts and shapes. 0.29.0 runs the cheap
+ * presence, closed-vocabulary and draft-marker checks
+ * (`shapes:draftSettled` per ADR-4126 scans the `[draft]` prefix).
+ * REQ-188 (0.30.0): the draft marker extends to `TAC.purpose` and
+ * `TAD.dataArchitecture.coreEntities[].description`; `shapes:draftSettled`
+ * enumerates all three homes with ids `<tacId>:<name>`, `<tacId>`
+ * and `TAD.entity:<name>` respectively. `tacHasInterface` and
+ * `kindVocabulary` apply to drafts unchanged.
  *
  * SEAM 0.30: template markers per kind (recordShape.fields:, httpRoute
  * method/path/request/response/errors, fixture.instances:); entity-name
- * join across TAD.coreEntities and TAC.interfaces[]; ownerRef and
- * `authoredAt` path resolution. Those add checks to this stage; the
- * fold shape stays the same.
+ * join across TAD.dataArchitecture.coreEntities and TAC.interfaces[];
+ * ownerRef and `authoredAt` path resolution. Those add checks to this
+ * stage; the fold shape stays the same.
  *
  * @param {StageContext} ctx
  */
@@ -443,8 +663,17 @@ export function checkD3Shapes(ctx) {
     return shapes.includes('httpApi') || shapes.includes('persistence') || shapes.includes('auth');
   });
 
-  if (tacsInScope.length === 0 && shapedReqInScope.length === 0) {
-    return notApplicable('D3', gate, 'no TAC and no shaped REQ (httpApi/persistence/auth) in scope');
+  // Core entities on TAD.dataArchitecture come from the whole tree,
+  // not the scope: an entity's draft marker is a tree-wide draft home
+  // (the engineer owns every entity in one place) and reporting it
+  // under D3 does not depend on which TAC a change touched.
+  const coreEntities = Array.isArray(tree.tad?.dataArchitecture?.coreEntities)
+    ? /** @type {any[]} */ (tree.tad.dataArchitecture.coreEntities)
+    : [];
+  const draftEntities = coreEntities.filter(parseCoreEntityDraft);
+
+  if (tacsInScope.length === 0 && shapedReqInScope.length === 0 && draftEntities.length === 0) {
+    return notApplicable('D3', gate, 'no TAC, no shaped REQ (httpApi/persistence/auth) and no [draft] core entity in scope');
   }
 
   const checks = [];
@@ -459,18 +688,39 @@ export function checkD3Shapes(ctx) {
   ));
 
   // Check 2: every interface kind is in the closed vocabulary.
+  // Check 3: no description across the three draft homes still
+  // carries the `[draft]` marker. A draft shape is entry material
+  // the agent pre-populates after L1; the engineer removes the
+  // marker when the shape is settled. `tacHasInterface` and
+  // `kindVocabulary` apply equally to drafts.
   let totalInterfaces = 0;
   const badKinds = [];
+  const draftFindings = [];
   for (const tac of tacsInScope) {
+    if (parseTacPurposeDraft(tac)) {
+      draftFindings.push({ id: tac.tacId, why: 'draft TAC purpose pre-populated at L1, not yet settled' });
+    }
     for (const iface of tac.interfaces ?? []) {
       totalInterfaces += 1;
       const kind = iface?.kind;
       if (typeof kind !== 'string' || !INTERFACE_KINDS_SET.has(kind)) {
         badKinds.push({ id: `${tac.tacId}:${iface?.name ?? '(unnamed)'}`, why: `unknown interface kind ${JSON.stringify(kind)}` });
       }
+      if (parseInterfaceDraft(iface)) {
+        draftFindings.push({ id: `${tac.tacId}:${iface?.name ?? '(unnamed)'}`, why: 'draft interface pre-populated at L1, not yet settled' });
+      }
     }
   }
+  for (const entity of draftEntities) {
+    draftFindings.push({ id: `TAD.entity:${entity?.name ?? '(unnamed)'}`, why: 'draft core entity pre-populated at L1, not yet settled' });
+  }
+  // Total for the draft check is every draft home that could carry
+  // the marker on an in-scope TAC plus every core entity (tree-wide):
+  // the TAC itself (its purpose) + every interface on it, plus the
+  // coreEntities list.
+  const totalDraftHomes = tacsInScope.length + totalInterfaces + coreEntities.length;
   checks.push(makeCheck('shapes:kindVocabulary', 'delta', totalInterfaces, badKinds));
+  checks.push(makeCheck('shapes:draftSettled', 'delta', totalDraftHomes, draftFindings));
 
   return foldState('D3', gate, checks, {
     currentTreeHash: ctx.currentTreeHash ?? null,
@@ -713,6 +963,31 @@ export function checkD7Decisions(ctx) {
   }
 
   const checks = [];
+  // Check 1: `decisions:wellFormed` (productOwner, over tree) --
+  // every decision is enumerated (ADR-4126, proposal section 1.3):
+  // a non-empty question, at least two options, a default that
+  // names one of the option letters.
+  const wellFormedFail = [];
+  for (const d of decisionEntries) {
+    const why = 'decision is not enumerated (question, two or more options, a default)';
+    const id = `decision:${d?.id ?? '?'}`;
+    if (typeof d?.question !== 'string' || d.question.length === 0) {
+      wellFormedFail.push({ id, why });
+      continue;
+    }
+    if (!Array.isArray(d.options) || d.options.length < 2) {
+      wellFormedFail.push({ id, why });
+      continue;
+    }
+    const letters = new Set(d.options.map((o) => (o && typeof o === 'object') ? /** @type {any} */ (o).letter : undefined));
+    if (typeof d.default !== 'string' || !letters.has(d.default)) {
+      wellFormedFail.push({ id, why });
+    }
+  }
+  checks.push(makeCheck('decisions:wellFormed', 'tree', decisionEntries.length, wellFormedFail));
+
+  // Check 2: `decisions:allAnswered` (engineer, over tree) -- zero
+  // open decisions. The hand-over condition for build.
   checks.push(makeCheck(
     'decisions:allAnswered',
     'tree',

package/src/query/index.js

@@ -13,15 +13,25 @@ export {
   computeDelta,
 } from './delta.js';
 // DEFINE stage gates (REQ-174; proposal §2.4, §3.2 v3). One check
-// function per stage; foldState + parseAcClass helpers.
+// function per stage; foldState + parseAcClass helpers. Persona /
+// question / draft-marker helpers added for ADR-4126 (0.29.0).
 export {
   STAGE_ORDER,
   STAGE_GATES,
   STAGE_SHORT_NAMES,
   STAGE_ALIASES,
   INTERFACE_KINDS,
+  CHECK_PERSONA,
+  CHECK_QUESTION,
+  STAGE_FALLBACK_PERSONA,
   stagePolicy,
   parseAcClass,
+  parseInterfaceDraft,
+  parseTacPurposeDraft,
+  parseCoreEntityDraft,
+  hasDraftMarker,
+  checkPersona,
+  checkQuestion,
   foldState,
   runStage,
   checkD1Brief,
@@ -33,10 +43,14 @@ export {
   checkD7Decisions,
   checkD8Freeze,
 } from './gates.js';
-// Readiness composer (REQ-175; proposal §2.4, §6 v3).
+// Readiness composer (REQ-175; proposal §2.4, §6 v3). Levels /
+// personas / verdict-line helpers added for ADR-4126 (0.29.0).
 export {
   computeReadiness,
   deriveNextAction,
+  deriveLevels,
+  derivePersonas,
+  formatVerdictLines,
   shortHash,
   formatTreeLine,
 } from './readiness.js';