rcf-lite 0.28.2 → 0.29.0

package/src/cli/readiness.js

@@ -0,0 +1,498 @@
+// `rcf define readiness` subcommand handler (REQ-175; proposal
+// 2026-09-22 §2.4, §6.2 v3; spec 2026-10-01 §2.3, §3, §4 for the
+// 0.29.0 PR B additions).
+//
+// Prints the readiness object (§2.4) or its JSON envelope. The 0.29.0
+// train added two verdict lines at the top of the text report (shared
+// with the Readiness tab via `formatVerdictLines`) and two new flags:
+// `--level intent|build` which drives the exit code against
+// `levels.<which>.ok` (stricter than `--check all` on warn-with-ack
+// failures, per spec section 3.2 decision 4; the `[warn]` line still
+// prints), and `--persona productOwner|engineer` which is a display
+// filter and never affects the exit code or JSON content. `--check`
+// behaviour is unchanged. The producer is wrapped with
+// `runWithAdmissibilityGate` (NV-BL-SR-03 addendum) so a chain that
+// refuses admissibility short-circuits with the same refusal envelope
+// every other query verb has.
+
+import { parseArgs } from 'node:util';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { resolveTestPointers, walkTree } from '#core/store';
+import { checkCodeNodeResolution } from '#core/store';
+import { findProjectRoot } from '../view/index.js';
+import { loadFreezeRecord } from '../define/freeze-record.js';
+import { loadAllLedgers } from '../define/ledgers.js';
+import {
+  STAGE_ALIASES,
+  STAGE_GATES,
+  STAGE_ORDER,
+  STAGE_SHORT_NAMES,
+  stagePolicy,
+} from '../query/gates.js';
+import {
+  computeReadiness,
+  formatTreeLine,
+  formatVerdictLines,
+  parseLevelFlag,
+  parsePersonaFlag,
+} from '../query/readiness.js';
+import { runWithAdmissibilityGate } from '../query/index.js';
+
+const OPTION_SPEC = {
+  json: { type: 'boolean' },
+  check: { type: 'string' },
+  level: { type: 'string' },
+  persona: { type: 'string' },
+  help: { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf define readiness [options]
+
+Compute and print the DEFINE readiness view: whether the tree is
+freezeable, which stage gate blocks, what the delta and its fan-out
+look like, and what the CLI recommends as the next action.
+
+The compute is pure: it composes the freeze delta, per-id impact,
+eight stage-gate checks (D1..D8), tree coverage and open decisions
+into one object. The viewer's Readiness tab (slice 5) will render the
+same object with no schema translation.
+
+The text report prints two verdict lines at the top (shared with the
+Readiness tab via formatVerdictLines): intent-complete (every
+product-owner question answered) and ready-to-build (equals
+freezeable). Blockers are grouped by persona, ordered by the
+profile.md register marker.
+
+Options:
+  --json                    Emit the full readiness object as JSON.
+                            --persona is ignored under --json.
+  --check <stage>           Narrow the output to one stage. Accepts a
+                            stage id (D1..D8) or its short name:
+                            brief | skeleton | shapes | stories |
+                            crosscut | consistency | decisions |
+                            freeze. Exits 4 on a blocking-stage
+                            failure (D1 / D2 / D4 / D7 / D8); exits 0
+                            with a visible '[warn]' line on an
+                            unacknowledged warn-with-ack failure
+                            (D3 / D5 / D6). Use --check all to print
+                            every stage under this exit-code policy.
+  --level <intent|build>    Pick which verdict the exit code follows.
+                            --level intent exits 4 when
+                            levels.intentComplete.ok is false
+                            (any failing product-owner check); exits
+                            0 otherwise. --level build exits 4 when
+                            levels.readyToBuild.ok is false, which is
+                            stricter than --check all on unacked
+                            warn-with-ack failures (the [warn] line
+                            still prints). Combined with --check, the
+                            invocation exits 4 if either policy
+                            says 4. With neither flag the exit code
+                            stays 0.
+  --persona <po|engineer>   Display filter for the text report.
+                            Values: productOwner | engineer. Collapses
+                            the opposite-persona block to one line
+                            with its check count and restricts the
+                            per-stage detail to matching-persona
+                            checks. Never affects the exit code or
+                            the JSON content.
+  --help                    Print this help.
+`;
+
+/** Text label per stage state, for the chip line. */
+const STATE_LABEL = {
+  passed: 'passed',
+  failing: 'failing',
+  acknowledged: 'acknowledged',
+  notApplicable: 'notApplicable',
+};
+
+/**
+ * Read `rcf/.identity/profile.md` when it exists; return null on
+ * ENOENT. Any other read error surfaces as null so the profile
+ * markers just fail to appear (the D1 check treats absence as a
+ * finding, not a runtime error).
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<string|null>}
+ */
+async function readProfileText(projectRoot) {
+  try {
+    return await readFile(join(projectRoot, 'rcf', '.identity', 'profile.md'), 'utf8');
+  } catch (err) {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT') return null;
+    return null;
+  }
+}
+
+/**
+ * Pick the profile register from the text, returning one of
+ * `productOwner` | `engineer` | `unstated`. The marker is a bare
+ * word match (same convention as `checkD1Brief`); the first marker
+ * found in the text wins. Absent or unrecognised yields `unstated`,
+ * which the text report orders as PO first (spec section 4).
+ *
+ * @param {string | null} text
+ * @returns {'productOwner' | 'engineer' | 'unstated'}
+ */
+function pickRegister(text) {
+  if (typeof text !== 'string' || text.length === 0) return 'unstated';
+  // Scan in file-order so the first marker in the document wins;
+  // this matches how a human reads `profile.md`.
+  const markers = ['productOwner', 'engineer', 'unstated'];
+  let best = null;
+  let bestIdx = Infinity;
+  for (const m of markers) {
+    const idx = text.indexOf(m);
+    if (idx === -1) continue;
+    if (idx < bestIdx) {
+      bestIdx = idx;
+      best = m;
+    }
+  }
+  return /** @type {any} */ (best) ?? 'unstated';
+}
+
+/**
+ * @param {string[]} argv
+ * @param {object} [deps]
+ * @returns {Promise<number>}
+ */
+export async function main(argv, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const cwd = deps.cwd ?? process.cwd();
+
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: OPTION_SPEC, allowPositionals: false, strict: true });
+  } catch (err) {
+    stderr.write(`[error] usage ${err.message}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  const flags = parsed.values;
+  if (flags.help) {
+    stdout.write(HELP);
+    return 0;
+  }
+
+  const checkArg = flags.check;
+  let checkStage = null;
+  if (typeof checkArg === 'string') {
+    if (checkArg === 'all') {
+      checkStage = 'all';
+    } else if (STAGE_ALIASES[checkArg]) {
+      checkStage = STAGE_ALIASES[checkArg];
+    } else {
+      stderr.write(`[error] usage readiness: unknown --check ${checkArg} (expected D1..D8, one of ${Object.values(STAGE_SHORT_NAMES).join(' | ')}, or 'all')\n`);
+      return 2;
+    }
+  }
+
+  /** @type {'intent' | 'build' | null} */
+  let level;
+  try {
+    level = parseLevelFlag(flags.level);
+  } catch (err) {
+    stderr.write(`[error] usage readiness: ${/** @type {Error} */ (err).message}\n`);
+    return 2;
+  }
+
+  /** @type {'productOwner' | 'engineer' | null} */
+  let persona;
+  try {
+    persona = parsePersonaFlag(flags.persona);
+  } catch (err) {
+    stderr.write(`[error] usage readiness: ${/** @type {Error} */ (err).message}\n`);
+    return 2;
+  }
+
+  const projectRoot = await findProjectRoot(cwd);
+  if (!projectRoot) {
+    stderr.write('[error] usage no project root found (no rcf/manifest.json in this directory or any ancestor). Run `npx rcf init` to create and wire a project.\n');
+    return 2;
+  }
+
+  const { tree, errors } = await walkTree({ projectRoot });
+  const staleErrors = await checkCodeNodeResolution({ projectRoot, tree });
+  const validateErrors = [...errors, ...staleErrors];
+
+  const [freeze, ledgers, testPointers, profileText] = await Promise.all([
+    loadFreezeRecord({ projectRoot }),
+    loadAllLedgers({ projectRoot }),
+    resolveTestPointers({ projectRoot, tree }),
+    readProfileText(projectRoot),
+  ]);
+
+  const startedAt = Date.now();
+  const chainRulesetVersion = typeof tree.manifest?.rulesetVersion === 'string'
+    ? tree.manifest.rulesetVersion
+    : null;
+
+  // Readiness is a diagnostic: even a chain that refuses admissibility
+  // wants to know which stage gate blocks it. The wrap runs first so
+  // the ruleset toolScope guard is honoured (NV-BL-SR-03 addendum);
+  // on refuse the refusal envelope is threaded through as informational
+  // context and the compute still runs (ADR-4123).
+  const gated = await runWithAdmissibilityGate({
+    tree,
+    chainRulesetVersion,
+    produce: () => computeReadiness(tree, {
+      freeze,
+      ledgers,
+      profile: undefined,
+      profileText,
+      testPointers,
+      validateErrors,
+    }),
+  });
+
+  /** @type {import('../query/readiness.js').ReadinessResult} */
+  const result = gated.status === 'refused-admissibility'
+    ? computeReadiness(tree, {
+      freeze, ledgers, profile: undefined, profileText, testPointers, validateErrors,
+    })
+    : gated.payload;
+  const wallMs = Date.now() - startedAt;
+
+  if (gated.status === 'refused-admissibility') {
+    stderr.write(`[warn] readiness: chain admissibility refused (informational; the readiness compute still ran). ${gated.refusal}\n`);
+  }
+
+  if (flags.json) {
+    // JSON emission carries the full object plus the wall-time hint
+    // and the invocation level as a stable side-band on `_meta`.
+    // `_meta.level` is null when the flag was absent (spec section
+    // 3.3): consumers can tell "no --level given" from "--level
+    // build" explicitly, which matters for the ticket artefact.
+    const envelope = { ...result, _meta: { wallMs, level } };
+    stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+    return decideExitCode(result, checkStage, level, stderr);
+  }
+
+  renderText(stdout, stderr, result, wallMs, checkStage, level, persona, profileText);
+  return decideExitCode(result, checkStage, level, stderr);
+}
+
+/**
+ * Emit the text summary (spec section 4):
+ *   1. Tree line.
+ *   2. Verdict pair (intent-complete, ready-to-build).
+ *   3. Next action, chip line, delta, coverage, decisions, freezeable
+ *      (today's lines; omitted when --check narrows to one stage).
+ *   4. Product-owner block and engineer block, ordered by the
+ *      profile.md register (PO first by default; engineer first when
+ *      the register is `engineer`; `unstated`/absent is PO first).
+ *      With --persona the opposite-persona block collapses to one
+ *      line; with --check <stage> the persona blocks are limited to
+ *      that stage.
+ *   5. Per-stage detail block (today's output; persona is now inside
+ *      the parenthesis after `over`). With --persona only the
+ *      matching-persona checks are rendered.
+ *
+ * @param {NodeJS.WritableStream} stdout
+ * @param {NodeJS.WritableStream} stderr
+ * @param {import('../query/readiness.js').ReadinessResult} result
+ * @param {number} wallMs
+ * @param {string | null} checkStage
+ * @param {'intent' | 'build' | null} level
+ * @param {'productOwner' | 'engineer' | null} persona
+ * @param {string | null} profileText
+ */
+function renderText(stdout, stderr, result, wallMs, checkStage, level, persona, profileText) {
+  stdout.write(`${formatTreeLine(result)}\n`);
+
+  const verdicts = formatVerdictLines(result);
+  stdout.write(`${verdicts.intentComplete}\n`);
+  stdout.write(`${verdicts.readyToBuild}\n`);
+
+  if (!checkStage || checkStage === 'all') {
+    renderNextActions(stdout, result, level);
+    stdout.write(`Chips: ${formatChipLine(result)}\n`);
+    stdout.write(`Delta: changed ${result.delta.changed.length}, added ${result.delta.added.length}, removed ${result.delta.removed.length}, briefSince ${result.delta.briefSince.length}, impacted ${result.delta.impacted.length}, impactedFbs ${result.delta.impactedFbs.length}.\n`);
+    stdout.write(`Coverage: tree ${result.coverage.tree.totals.covered}/${result.coverage.tree.totals.requirements} covered (strict), ${result.coverage.delta.length} REQ ancestor(s) scoped from the delta.\n`);
+    stdout.write(`Decisions open: ${result.decisions.length}.\n`);
+    stdout.write(`Freezeable: ${result.freezeable ? 'yes' : 'no'}. Compute: ${wallMs} ms.\n`);
+  }
+
+  const register = pickRegister(profileText);
+  renderPersonaBlocks(stdout, result, persona, register, checkStage);
+
+  for (const stage of result.stages) {
+    if (checkStage && checkStage !== 'all' && stage.stage !== checkStage) continue;
+    stdout.write(`\n${stage.stage} (${stage.gate}): ${STATE_LABEL[stage.state] ?? stage.state}${stage.reason ? ` (${stage.reason})` : ''}\n`);
+    for (const c of stage.checks) {
+      if (persona && c.persona !== persona) continue;
+      const mark = c.ok ? 'ok' : 'FAIL';
+      stdout.write(`  [${mark}] ${c.name} (${c.over}, ${c.persona}): ${c.pass}/${c.total}\n`);
+      for (const f of c.failing.slice(0, 20)) {
+        stdout.write(`      - ${f.id}: ${f.why}\n`);
+      }
+      if (c.failing.length > 20) {
+        stdout.write(`      ... ${c.failing.length - 20} more suppressed\n`);
+      }
+    }
+  }
+}
+
+/**
+ * Render the per-persona next-action lines (spec section 4). When a
+ * `--level` is given the matching persona's line heads the pair; when
+ * no `--level` is given the pair follows the register order. Each
+ * line is `Next action (<persona>): <stage> / <check>; ids: ...`.
+ *
+ * @param {NodeJS.WritableStream} stdout
+ * @param {import('../query/readiness.js').ReadinessResult} result
+ * @param {'intent' | 'build' | null} level
+ */
+function renderNextActions(stdout, result, level) {
+  const po = result.personas.productOwner.nextAction;
+  const eng = result.personas.engineer.nextAction;
+  const writeAction = (label, action) => {
+    if (!action) {
+      stdout.write(`Next action (${label}): none.\n`);
+      return;
+    }
+    const ids = action.ids.length > 0 ? `; ids: ${action.ids.join(', ')}` : '';
+    stdout.write(`Next action (${label}): ${action.stage} / ${action.check}${ids}. Run \`${action.command}\` after editing.\n`);
+  };
+  writeAction('product owner', po);
+  writeAction('engineer', eng);
+}
+
+/**
+ * Render the two persona-grouped blocker blocks (spec section 4).
+ * `register` orders the pair; `persona` (the display filter) collapses
+ * the opposite block to one count line; `checkStage` (when not null
+ * or 'all') restricts both blocks to blockers in that stage.
+ *
+ * @param {NodeJS.WritableStream} stdout
+ * @param {import('../query/readiness.js').ReadinessResult} result
+ * @param {'productOwner' | 'engineer' | null} persona
+ * @param {'productOwner' | 'engineer' | 'unstated'} register
+ * @param {string | null} checkStage
+ */
+function renderPersonaBlocks(stdout, result, persona, register, checkStage) {
+  const stageFilter = (bs) => (checkStage && checkStage !== 'all'
+    ? bs.filter((b) => b.stage === checkStage)
+    : bs);
+  // L1 blockedBy for the PO list (ignores stage state); L2 blockedBy
+  // minus PO entries for the engineer list, matching
+  // `personas.engineer.blockers`.
+  const poBlockers = stageFilter(result.personas.productOwner.blockers);
+  const engineerBlockers = stageFilter(result.personas.engineer.blockers);
+
+  const order = register === 'engineer'
+    ? [['engineer', engineerBlockers], ['productOwner', poBlockers]]
+    : [['productOwner', poBlockers], ['engineer', engineerBlockers]];
+
+  for (const [p, blockers] of order) {
+    stdout.write('\n');
+    const headerLabel = p === 'productOwner' ? 'Product owner' : 'Engineer';
+    const noun = p === 'productOwner' ? 'question' : 'check blocking';
+    const nounPlural = p === 'productOwner' ? 'questions' : 'checks blocking';
+    if (persona && p !== persona) {
+      stdout.write(`${headerLabel}: ${blockers.length} ${blockers.length === 1 ? noun : nounPlural} (hidden; run without --persona)\n`);
+      continue;
+    }
+    if (blockers.length === 0) {
+      stdout.write(`${headerLabel}: 0 ${nounPlural}.\n`);
+      continue;
+    }
+    stdout.write(`${headerLabel}: ${blockers.length} ${blockers.length === 1 ? noun : nounPlural}\n`);
+    for (const b of blockers) {
+      stdout.write(`  ${b.stage} ${b.check}: ${b.question} ${b.failingCount}/${b.failingCount}\n`);
+      for (const id of b.ids.slice(0, 20)) {
+        stdout.write(`      - ${id}\n`);
+      }
+      if (b.failingCount > b.ids.length) {
+        stdout.write(`      ... ${b.failingCount - b.ids.length} more suppressed\n`);
+      }
+    }
+  }
+}
+
+/**
+ * Compose the chip line: "D1:passed D2:failing D3:acknowledged ..."
+ *
+ * @param {import('../query/readiness.js').ReadinessResult} result
+ * @returns {string}
+ */
+function formatChipLine(result) {
+  return result.stages.map((s) => `${s.stage}:${s.state}`).join(' ');
+}
+
+/**
+ * Decide the exit code for an invocation (spec section 3.2 matrix):
+ *   - No `--check` and no `--level`: always 0.
+ *   - `--check` alone: today's stage policy (4 on blocking failure,
+ *     0 with `[warn]` on warn-with-ack failure).
+ *   - `--level intent`: 4 iff `levels.intentComplete.ok === false`.
+ *   - `--level build`: 4 iff `levels.readyToBuild.ok === false`
+ *     (stricter than `--check all`; the warn line still prints).
+ *   - Both: 4 if either policy says 4.
+ *
+ * Warn lines are emitted whenever a warn-with-ack stage is failing,
+ * independent of exit code, so an operator always sees why.
+ *
+ * @param {import('../query/readiness.js').ReadinessResult} result
+ * @param {string | null} checkStage
+ * @param {'intent' | 'build' | null} level
+ * @param {NodeJS.WritableStream} stderr
+ * @returns {number}
+ */
+function decideExitCode(result, checkStage, level, stderr) {
+  let exitCode = 0;
+
+  // --check policy (unchanged from PR A).
+  if (checkStage) {
+    const stages = checkStage === 'all'
+      ? result.stages
+      : result.stages.filter((s) => s.stage === checkStage);
+    for (const s of stages) {
+      if (s.state !== 'failing') continue;
+      const policy = stagePolicy(s.stage);
+      if (policy === 'blocking') {
+        exitCode = 4;
+      } else {
+        stderr.write(`[warn] readiness: ${s.stage} (${s.gate}) is failing without an acknowledgement at the current tree hash. Run \`rcf define freeze --ack ${s.gate} --reason "<text>"\` to acknowledge, or edit the tree to clear the failure.\n`);
+      }
+    }
+  }
+
+  // --level policy. When explicit, exit 4 if that level says "no".
+  // --level build is stricter than --check all: it exits 4 even on an
+  // unacknowledged warn-with-ack failure (spec decision 4). The warn
+  // lines are still emitted (above when --check all is also set, or
+  // here when --level build is given alone).
+  if (level === 'intent' && result.levels.intentComplete.ok === false) {
+    exitCode = 4;
+  } else if (level === 'build' && result.levels.readyToBuild.ok === false) {
+    exitCode = 4;
+    // When --level build is set without --check all, we have not yet
+    // emitted the per-stage warn lines. Emit them here so an operator
+    // still sees which warn-with-ack stage drove the "no".
+    if (!checkStage || checkStage !== 'all') {
+      const seen = new Set();
+      if (checkStage) {
+        // --level build + --check <stage>: the --check branch already
+        // emitted that stage's warn line (if any). Avoid duplicates.
+        seen.add(checkStage);
+      }
+      for (const s of result.stages) {
+        if (seen.has(s.stage)) continue;
+        if (s.state !== 'failing') continue;
+        if (stagePolicy(s.stage) === 'blocking') continue;
+        stderr.write(`[warn] readiness: ${s.stage} (${s.gate}) is failing without an acknowledgement at the current tree hash. Run \`rcf define freeze --ack ${s.gate} --reason "<text>"\` to acknowledge, or edit the tree to clear the failure.\n`);
+      }
+    }
+  }
+
+  return exitCode;
+}
+
+// Re-export the gate map so consumers importing this module (help,
+// slice 3) share one seam.
+export { STAGE_GATES, STAGE_ORDER, STAGE_SHORT_NAMES };

package/src/cli/view.js

@@ -92,6 +92,13 @@ Options:
                     and CI is unset).
   --verbose         Log each watch event and each SSE broadcast to
                     stderr.
+  --test-host       Mount the wespa host fixture at /test-host.html
+                    plus its client script at /test-host.js. Off by
+                    default; the fixture is a test-suite proof that
+                    the viewer honours Dex's embedding contract (viewer
+                    UI refresh PR 9; TAC-4134, ADR-4136), not a shipped
+                    UI, so wespa's reverse-proxy allow-list is
+                    unaffected. Can also be set via RCF_VIEW_TEST_HOST=1.
   --help            Print this help and exit.
 
 Security posture:
@@ -130,6 +137,7 @@ export function parseArgs(argv) {
     help: false,
     noOpen: false,
     port: null,
+    testHost: false,
   };
   const errors = [];
   for (let i = 0; i < argv.length; i += 1) {
@@ -148,6 +156,13 @@ export function parseArgs(argv) {
       case '-h':
         opts.help = true;
         break;
+      case '--test-host':
+        // Viewer UI refresh PR 9 (TAC-4134, ADR-4136): mount the wespa
+        // host fixture at /test-host.html plus its client at
+        // /test-host.js. Off by default; the fixture is a test-suite
+        // proof, not a shipped UI.
+        opts.testHost = true;
+        break;
       case '--port': {
         const next = argv[i + 1];
         if (next === undefined || next.startsWith('--')) {
@@ -170,6 +185,19 @@ export function parseArgs(argv) {
   return { opts, errors };
 }
 
+/**
+ * Resolve the testHost gate: `--test-host` beats `RCF_VIEW_TEST_HOST=1`
+ * env beats default (false). Viewer UI refresh PR 9 (TAC-4134).
+ *
+ * @param {boolean} flagTestHost
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {boolean}
+ */
+export function resolveTestHost(flagTestHost, env) {
+  if (flagTestHost === true) return true;
+  return env.RCF_VIEW_TEST_HOST === '1';
+}
+
 /**
  * Resolve port precedence: --port beats RCF_VIEW_PORT env beats default.
  *
@@ -294,6 +322,7 @@ export async function main(argv, deps = {}) {
       projectRoot,
       port: resolvedPort,
       log: logSink,
+      testHost: resolveTestHost(opts.testHost, env),
     });
   } catch (err) {
     if (/** @type {NodeJS.ErrnoException} */ (err).code === 'EADDRINUSE') {

package/src/core/store/writer.js

@@ -200,18 +200,98 @@ export function nextIdForKind(tree, kind, opts = {}) {
       // one numbering group.
       const groupNum = Number(normaliseId(match[1]));
       const groupLabel = String(groupNum);
+      // Occupancy is every US id in the tree. Each id is classified as
+      // ENCODED (`US-<reqNum><localTwoDigit>` where the reqNum names an
+      // existing REQ and local is 01..99) or FLAT (a bare sequential
+      // number that carries no parent-encoded suffix, as produced by
+      // legacy trees migrated in from WESPA v1). Classification decides
+      // the allocation rule:
+      //   - all-encoded tree (or empty): the historical rule, extend
+      //     `US-<groupLabel><nextLocal>`.
+      //   - all-flat tree: extend the flat sequence past the highest
+      //     existing US number (issue #256 / w-2026-09-29-dave-005).
+      //   - mixed tree: refuse the mint with an explicit error naming
+      //     both schemes, so an operator normalises the tree before a
+      //     new id is issued (Dave disposition 2026-09-30).
+      // AC minting is unchanged; #256 was reproduced against USes only.
+      // Classification prefers the doc's declared reqId (unambiguous) over
+      // the id-only heuristic. Without that, a legacy US-163 filed under
+      // REQ-053 would decompose as parent=1/local=63 and look encoded
+      // whenever REQ-001 happened to exist, defeating the whole rule.
+      const usIds = occupiedIdsOfKind(tree, 'userStory');
+      const reqNums = new Set();
+      for (const rId of occupiedIdsOfKind(tree, 'req')) {
+        const rn = idNumber(rId, 'REQ');
+        if (rn !== null) reqNums.add(rn);
+      }
+      const encoded = [];
+      const flat = [];
+      const seenUsNums = new Set();
+      for (const usId of usIds) {
+        const num = idNumber(usId, 'US');
+        if (num === null) continue;
+        // occupiedIdsOfKind emits both the on-disk id and the doc's
+        // declared id field, so the same numeric id appears twice.
+        // Dedupe on the numeric value to avoid double-counting.
+        if (seenUsNums.has(num)) continue;
+        seenUsNums.add(num);
+        const localPart = num % 100;
+        const parentPart = Math.floor(num / 100);
+        const doc = tree.byId.get(usId);
+        let declaredReqNum = null;
+        if (doc && typeof doc.reqId === 'string') {
+          const mReq = /^REQ-(\d+)$/.exec(doc.reqId);
+          if (mReq) declaredReqNum = Number(normaliseId(mReq[1]));
+        }
+        let isEncoded;
+        if (declaredReqNum !== null) {
+          // Encoded iff the id decomposes as <declaredReqNum><two-digit
+          // local in 01..99>. Any other shape is flat.
+          isEncoded = (localPart >= 1 && localPart <= 99 && parentPart === declaredReqNum);
+        } else {
+          // Invalid / unloadable doc: fall back to the id-only heuristic
+          // (matches historical behaviour when the parent-part names an
+          // existing REQ).
+          isEncoded = (localPart >= 1 && localPart <= 99 && reqNums.has(parentPart));
+        }
+        if (isEncoded) {
+          encoded.push({ id: usId, num, parentPart, localPart });
+        } else {
+          flat.push({ id: usId, num });
+        }
+      }
+
+      if (encoded.length > 0 && flat.length > 0) {
+        const encodedExample = encoded[0].id;
+        const flatExample = flat[0].id;
+        throw new TypeError(
+          'nextIdForKind us: refusing to mint - the tree mixes '
+          + `encoded US ids (e.g. ${encodedExample}, shape US-<reqNum><localTwoDigit>) `
+          + `and flat US ids (e.g. ${flatExample}, shape US-<seq>). `
+          + 'Normalise every US id to one scheme (rename the outliers, '
+          + 'update every reference) and retry, or ask HQ for a bulk '
+          + 're-mint. Auto-mint intentionally refuses on ambiguous trees.',
+        );
+      }
+
+      if (flat.length > 0 && encoded.length === 0) {
+        let maxFlat = 0;
+        for (const f of flat) {
+          if (f.num > maxFlat) maxFlat = f.num;
+        }
+        return `US-${maxFlat + 1}`;
+      }
+
+      // All-encoded (or empty) tree: keep the historical behaviour.
       // Occupancy is every US id that numerically falls in this group,
       // whatever `reqId` string it names. Filtering on an exact reqId
       // string match was the bug: a US filed under `REQ-0001` was
       // invisible when allocating for `REQ-001`, so US-101 got re-issued
       // on top of the existing US-101.
-      const usIds = occupiedIdsOfKind(tree, 'userStory');
       let maxLocal = 0;
-      for (const usId of usIds) {
-        const num = idNumber(usId, 'US');
-        if (num === null) continue;
-        const local = num - groupNum * 100;
-        if (local >= 1 && local <= 99 && local > maxLocal) maxLocal = local;
+      for (const e of encoded) {
+        if (e.parentPart !== groupNum) continue;
+        if (e.localPart > maxLocal) maxLocal = e.localPart;
       }
       const nextLocal = maxLocal + 1;
       return `US-${groupLabel}${String(nextLocal).padStart(2, '0')}`;