rcf-lite 0.0.1 → 0.7.1

package/src/core/store/derive-deps.js

@@ -0,0 +1,93 @@
+// Phase 10 (X2 CodeNode bridge, spec D5): optional dev-time assist that
+// shells out to `dependency-cruiser` for file-level dependency
+// auto-derivation. NEVER a runtime dependency - `rcf` carries a public
+// zero-third-party-runtime-deps claim (Phase 9 D14) that this module does
+// not touch: it only ever invokes an external binary via child_process,
+// only when the caller opts in with `--derive-deps`, and it never appears
+// in package.json.
+//
+// PoC exp 3 evidence: dependency-cruiser beat hand-declaration at file
+// level (8/8 agreement on hand-declared edges, plus 3 real edges the
+// human missed - 73% human recall). Symbol-level derivation is out of
+// reach for this tool (file-granular only, PoC-confirmed); symbol
+// dependencies stay hand-declared or omitted (D5, out of scope SS6).
+//
+// `--no-install` on the npx invocation is load-bearing: this module must
+// never trigger a network install as a side effect of a CLI flag. When
+// the tool is not resolvable (no local install, npx would need to
+// fetch it), the caller gets a helpful error, not a silent hang or a
+// surprise download.
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+export const NOT_RESOLVABLE_MESSAGE =
+  'dependency-cruiser is not resolvable (no local install, and npx --no-install will not fetch it). '
+  + 'Install it as a dev dependency in this project (npm install --save-dev dependency-cruiser) to use '
+  + '--derive-deps, or declare --deps by hand.';
+
+/**
+ * Derive the file-level dependencies of `filePath` (repo-relative, no
+ * `#symbol` suffix) via `dependency-cruiser`. Resolved locally or via
+ * `npx --no-install`; never attempts to install anything.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot - absolute path to project root
+ * @param {string} args.filePath - repo-relative source path (no #symbol)
+ * @param {(cmd: string, cmdArgs: string[], opts: object) => Promise<{stdout: string}>} [args.exec]
+ *   Injection seam for tests - defaults to the real child_process call.
+ * @returns {Promise<{ ok: true, deps: string[] } | { ok: false, message: string }>}
+ */
+export async function deriveFileDeps({ projectRoot, filePath, exec = execFileAsync }) {
+  let stdout;
+  try {
+    ({ stdout } = await exec('npx', ['--no-install', 'dependency-cruiser', '--output-type', 'json', filePath], {
+      cwd: projectRoot,
+    }));
+  } catch {
+    return { ok: false, message: NOT_RESOLVABLE_MESSAGE };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch (err) {
+    return { ok: false, message: `dependency-cruiser produced unparseable output: ${err.message}` };
+  }
+  const modules = Array.isArray(parsed?.modules) ? parsed.modules : [];
+  const self = modules.find((m) => m.source === filePath);
+  const deps = (self?.dependencies ?? [])
+    .filter((d) => d.resolved && d.dependencyTypes?.every((t) => t !== 'npm' && t !== 'core'))
+    .map((d) => d.resolved)
+    .sort();
+  return { ok: true, deps: [...new Set(deps)] };
+}
+
+/**
+ * Map derived file-level dependency paths to existing Code Node ids
+ * whose `path` (file part, ignoring any `#symbol` suffix) matches. A
+ * derived file with no matching CN cannot become a dependency edge (D3:
+ * `dependencies[]` is CN -> CN, not CN -> bare file) - such files are
+ * reported separately so the caller can surface them informationally.
+ *
+ * @param {object} tree - walker TreeModel
+ * @param {string[]} filePaths
+ * @returns {{ cnIds: string[], unmatched: string[] }}
+ */
+export function mapDerivedDepsToCnIds(tree, filePaths) {
+  const cnIds = new Set();
+  const unmatched = [];
+  for (const filePath of filePaths) {
+    const matches = (tree.codeNodes ?? [])
+      .filter((cn) => (cn.path ?? '').split('#')[0] === filePath)
+      .map((cn) => cn.cnId)
+      .sort();
+    if (matches.length === 0) {
+      unmatched.push(filePath);
+    } else {
+      for (const id of matches) cnIds.add(id);
+    }
+  }
+  return { cnIds: [...cnIds].sort(), unmatched };
+}

package/src/core/store/ids.js

@@ -0,0 +1,78 @@
+// Id normalisation. The RCF id patterns in `@stravica-ai/rcf-schemas`
+// admit a variable-width numeric run (`^REQ-\d{3,}$`, `^US-\d{3,}$`,
+// `^AC-\d{3,}(-\d+)?$`, ...), so `REQ-001` and `REQ-0001` are BOTH legal
+// and BOTH name requirement number 1. The schema is right to permit the
+// widths -- an id space that outgrows three digits has to be expressible
+// -- but two spellings of one number are one identity, not two.
+//
+// This module owns the single definition of "the same id" used by the
+// walker's uniqueness rule (`globallyUniqueIds`) and by the writer's id
+// allocator. Both sides MUST agree: detection that normalises while
+// allocation does not just moves the collision one step later.
+//
+// Normalisation is per hyphen-delimited segment and only touches
+// segments that are entirely digits:
+//
+//   REQ-001      -> REQ-1
+//   REQ-0001     -> REQ-1        (collides with REQ-001, correctly)
+//   AC-101-01    -> AC-101-1     (collides with AC-101-1, correctly)
+//   TC-001-step2 -> TC-1-step2   (the slug segment is left alone)
+//
+// Leaving non-numeric segments untouched is deliberate: a TC slug like
+// `step02` is a word, not a number, and must not be folded into `step2`.
+
+/**
+ * Strip leading zeros from a run of digits without going through Number
+ * (precision-safe for arbitrarily long numeric segments).
+ *
+ * @param {string} digits
+ * @returns {string}
+ */
+function stripLeadingZeros(digits) {
+  const trimmed = digits.replace(/^0+(?=\d)/, '');
+  return trimmed.length > 0 ? trimmed : '0';
+}
+
+/**
+ * Canonical form of an RCF id for identity comparison. Two ids are the
+ * same id if and only if their normalised forms are equal.
+ *
+ * @param {unknown} id
+ * @returns {string} normalised id, or '' when the input is not a string
+ */
+export function normaliseId(id) {
+  if (typeof id !== 'string') return '';
+  return id
+    .split('-')
+    .map((segment) => (/^\d+$/.test(segment) ? stripLeadingZeros(segment) : segment))
+    .join('-');
+}
+
+/**
+ * Identity comparison for two RCF ids, tolerant of leading-zero spelling.
+ *
+ * @param {unknown} a
+ * @param {unknown} b
+ * @returns {boolean}
+ */
+export function sameId(a, b) {
+  const na = normaliseId(a);
+  return na.length > 0 && na === normaliseId(b);
+}
+
+/**
+ * Numeric value of an id's first numeric segment after the prefix, or
+ * null when the id does not match `<PREFIX>-<digits>`. Used by the
+ * allocator to reason about id numbers independently of their spelling.
+ *
+ * @param {unknown} id
+ * @param {string} prefix - e.g. 'REQ', 'US'
+ * @returns {number|null}
+ */
+export function idNumber(id, prefix) {
+  if (typeof id !== 'string') return null;
+  const m = new RegExp(`^${prefix}-(\\d+)(?:-|$)`).exec(id);
+  if (!m) return null;
+  const n = Number(m[1]);
+  return Number.isSafeInteger(n) ? n : null;
+}

package/src/core/store/index.js

@@ -0,0 +1,20 @@
+// Document store - public surface for the Phase 3 dispatch.
+//
+// Every consumer (the view, future CLI verbs, future MCP tools) reaches the
+// filesystem through this module. No other layer reads from or writes to
+// rcf/ directly.
+
+export { loadDocument, loadRootDocument, pathForId, rootPathFor, subdirFor } from './loader.js';
+// w-2026-07-28-017: id identity (leading-zero-tolerant). Shared by the
+// walker's globallyUniqueIds rule and the writer's allocator.
+export { idNumber, normaliseId, sameId } from './ids.js';
+export { validateDocument, idFieldFor, documentIdOf, knownKinds } from './validator.js';
+export { netNewErrors, simulateWriteErrors, walkTree } from './walker.js';
+export { initProject } from './init.js';
+// Phase 10 (X2 CodeNode bridge): Code Node working-tree staleness check.
+export { checkCodeNodeResolution, splitCnPath } from './cn-resolve.js';
+// w-2026-07-28-005: Test Case pointer working-tree resolution (test-axis
+// twin of cn-resolve). Coverage consumes this - an unresolved pointer is
+// never counted as covering an AC.
+export { resolveTestPointers, splitTestPointer, testCaseKey } from './tp-resolve.js';
+export { nextIdForKind, createDocument, updateDocument, deleteDocument, deriveSlug } from './writer.js';

package/src/core/store/init.js

@@ -0,0 +1,255 @@
+// Project scaffolding. Creates a minimum valid rcf/ tree (manifest plus a
+// placeholder PRD, REQ, US, TAD, TAC, ADR, BS, FBS) so a fresh repo has a
+// schema-clean starting point. Every required field carries a TODO marker
+// so the owner can see what they need to fill in.
+//
+// AC-101-2: refuses to overwrite an existing project. If rcf/manifest.json
+// already exists, this function writes nothing and returns a usage error.
+//
+// Phase 3.7 D14 shape: parent-child edges live on the child. The PRD
+// no longer carries `requirementIds`; each REQ carries `prdId` (already
+// present). The TAD no longer carries `componentIds` /
+// `architecturalDecisionIds`; each TAC / ADR carries `tadId`. The BS
+// no longer carries `fbs[]`; each FBS carries `bsId`, `buildOrder`,
+// `executionStatus` and `dependsOnFbsIds`. The empty `rcf/test-suites/`
+// directory is scaffolded so a future authored TS drops into a
+// pre-existing shape.
+//
+// Phase 4 D5: `seed` accepts overrides for the four interactive prompts
+// (`prdProblemStatement`, `reqTitle`, `usTitle`, and any of the values
+// the interactive `rcf init` UX collects). When `seed.interactive` is
+// truthy the ADR-001 template starts in `draft` rather than `proposed`,
+// matching interactive-mode intent (D22 amendment).
+
+import { mkdir, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { rcfError } from '../errors/index.js';
+
+const TIMESTAMP = '2026-01-01T00:00:00Z';
+
+function manifestTemplate(projectName) {
+  return {
+    version: '2.0.0',
+    projectName,
+    description: 'RCF project manifest. Roots are declared here; children are walked from the roots.',
+    prd: { id: 'PRD-001', path: 'prd.json' },
+    tad: { id: 'TAD-001', path: 'tad.json' },
+    bs: { id: 'BS-001', path: 'build-sequence.json' },
+  };
+}
+
+function prdTemplate(projectName, seed) {
+  return {
+    prdId: 'PRD-001',
+    productName: projectName,
+    version: '0.1.0',
+    status: 'draft',
+    problemStatement: seed?.prdProblemStatement ?? 'TODO: state the problem this product solves.',
+    objectives: seed?.prdProblemStatement
+      ? [seed.prdProblemStatement]
+      : ['TODO: add at least one objective.'],
+    createdAt: TIMESTAMP,
+    updatedAt: TIMESTAMP,
+  };
+}
+
+function reqTemplate(seed) {
+  return {
+    reqId: 'REQ-001',
+    prdId: 'PRD-001',
+    title: seed?.reqTitle ?? 'TODO: name this requirement',
+    description: seed?.reqTitle ?? 'TODO: describe this requirement.',
+    category: 'functional',
+    domain: 'todo',
+    priority: 'must',
+    version: '0.1.0',
+    status: 'draft',
+    createdAt: TIMESTAMP,
+    updatedAt: TIMESTAMP,
+  };
+}
+
+function userStoryTemplate(seed) {
+  const interactive = Boolean(seed?.interactive);
+  return {
+    usId: 'US-101',
+    prdId: 'PRD-001',
+    reqId: 'REQ-001',
+    version: '0.1.0',
+    status: 'draft',
+    title: seed?.usTitle ?? 'TODO: name this user story',
+    // Interactive mode leaves the As-a / I want / So that fields as
+    // minimal "-" placeholders (schema requires minLength: 1 so an empty
+    // string would fail validation; the spec's "empty is allowed"
+    // claim on this field was inaccurate on inspection).
+    asA: interactive ? '-' : 'TODO: name the user',
+    iWant: interactive ? '-' : 'TODO: state the want',
+    soThat: interactive ? '-' : 'TODO: state the value',
+    acceptanceCriteria: [
+      {
+        id: 'AC-101-1',
+        description: 'TODO: describe the first acceptance criterion',
+        testable: true,
+      },
+    ],
+    createdAt: TIMESTAMP,
+    updatedAt: TIMESTAMP,
+  };
+}
+
+function tadTemplate() {
+  return {
+    tadId: 'TAD-001',
+    prdId: 'PRD-001',
+    version: '0.1.0',
+    status: 'draft',
+    systemOverview: {
+      executiveSummary: 'TODO: one-paragraph system overview.',
+      systemPurpose: 'TODO: state the system purpose.',
+      architecturalApproach: 'TODO: state the architectural approach.',
+      keyCapabilities: ['TODO: list at least one key capability.'],
+    },
+    createdAt: TIMESTAMP,
+    updatedAt: TIMESTAMP,
+  };
+}
+
+function tacTemplate() {
+  return {
+    tacId: 'TAC-001',
+    prdId: 'PRD-001',
+    tadId: 'TAD-001',
+    version: '0.1.0',
+    status: 'draft',
+    name: 'TODO: name this component',
+    purpose: 'TODO: state the purpose of this component.',
+    responsibilities: ['TODO: list at least one responsibility.'],
+    createdAt: TIMESTAMP,
+    updatedAt: TIMESTAMP,
+  };
+}
+
+function adrTemplate(seed) {
+  return {
+    adrId: 'ADR-001',
+    prdId: 'PRD-001',
+    tadId: 'TAD-001',
+    version: '0.1.0',
+    // Interactive-mode `rcf init` seeds ADR-001 in `draft`
+    // (Phase 3.7 D2 grew the enum; Phase 4 D22 uses it here);
+    // non-interactive mode keeps the historical `proposed` value.
+    status: seed?.interactive ? 'draft' : 'proposed',
+    title: 'TODO: name this architectural decision',
+    context: 'TODO: describe the context.',
+    decision: 'TODO: describe the decision.',
+    consequences: 'TODO: describe the consequences.',
+    createdAt: TIMESTAMP,
+    updatedAt: TIMESTAMP,
+  };
+}
+
+function buildSequenceTemplate() {
+  return {
+    bsId: 'BS-001',
+    prdId: 'PRD-001',
+    version: '0.1.0',
+    status: 'draft',
+    title: 'Initial build sequence',
+    buildPhilosophy: 'TODO: describe the build philosophy.',
+    generationStrategy: 'dependencyFirst',
+    createdAt: TIMESTAMP,
+    updatedAt: TIMESTAMP,
+  };
+}
+
+function fbsTemplate() {
+  return {
+    fbsId: 'FBS-001',
+    prdId: 'PRD-001',
+    bsId: 'BS-001',
+    buildOrder: 1,
+    executionStatus: 'notStarted',
+    title: 'TODO: name this build session',
+    summary: 'TODO: describe what this build session delivers.',
+    acIds: ['AC-101-1'],
+    dependsOnFbsIds: [],
+    createdAt: TIMESTAMP,
+    updatedAt: TIMESTAMP,
+  };
+}
+
+async function exists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch (err) {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT') return false;
+    throw err;
+  }
+}
+
+async function writeJson(path, data) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+
+/**
+ * Scaffold a minimum valid rcf/ tree at `projectRoot`. Idempotent against an
+ * empty target; refuses if rcf/manifest.json already exists.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot - absolute path; created if missing
+ * @param {string} [args.projectName] - written into manifest and PRD
+ * @param {object} [args.seed] - optional interactive-mode overrides
+ * @param {boolean} [args.seed.interactive]
+ * @param {string} [args.seed.prdProblemStatement]
+ * @param {string} [args.seed.reqTitle]
+ * @param {string} [args.seed.usTitle]
+ * @returns {Promise<{ created: string[] } | import('../errors/index.js').RcfError>}
+ */
+export async function initProject({ projectRoot, projectName = 'New RCF Project', seed = null }) {
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
+    return rcfError({
+      kind: 'usage',
+      message: 'initProject requires projectRoot',
+    });
+  }
+  const manifestPath = join(projectRoot, 'rcf', 'manifest.json');
+  if (await exists(manifestPath)) {
+    return rcfError({
+      kind: 'usage',
+      message: 'An RCF project already exists at this path (rcf/manifest.json present)',
+      filePath: 'rcf/manifest.json',
+    });
+  }
+  const dirs = [
+    'rcf',
+    'rcf/requirements',
+    'rcf/user-stories',
+    'rcf/tacs',
+    'rcf/adrs',
+    'rcf/fbs',
+    'rcf/test-suites',
+  ];
+  for (const d of dirs) {
+    await mkdir(join(projectRoot, d), { recursive: true });
+  }
+
+  const files = [
+    ['rcf/manifest.json', manifestTemplate(projectName)],
+    ['rcf/prd.json', prdTemplate(projectName, seed)],
+    ['rcf/requirements/req-001.json', reqTemplate(seed)],
+    ['rcf/user-stories/us-101.json', userStoryTemplate(seed)],
+    ['rcf/tad.json', tadTemplate()],
+    ['rcf/tacs/tac-001.json', tacTemplate()],
+    ['rcf/adrs/adr-001.json', adrTemplate(seed)],
+    ['rcf/build-sequence.json', buildSequenceTemplate()],
+    ['rcf/fbs/fbs-001.json', fbsTemplate()],
+  ];
+  for (const [relPath, data] of files) {
+    await writeJson(join(projectRoot, relPath), data);
+  }
+
+  return { created: files.map(([p]) => p) };
+}

package/src/core/store/loader.js

@@ -0,0 +1,211 @@
+// Document loader. Resolves an id (or a manifest-relative path) under the
+// project's rcf/ tree, reads the file, parses JSON, validates against the
+// matching schema, and returns the document or a structured error.
+//
+// This is the only place that touches the filesystem on the read path; the
+// walker, the validate command and the view layer all go through it.
+
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { rcfError } from '../errors/index.js';
+import { validateDocument } from './validator.js';
+
+/**
+ * Map a document kind to the subdirectory under rcf/ it lives in. The root
+ * documents (manifest, prd, tad, buildSequence) live at the rcf root and
+ * return null.
+ *
+ * @param {string} kind
+ * @returns {string|null}
+ */
+export function subdirFor(kind) {
+  switch (kind) {
+    case 'req': return 'requirements';
+    case 'userStory': return 'user-stories';
+    case 'tac': return 'tacs';
+    case 'adr': return 'adrs';
+    case 'fbs': return 'fbs';
+    case 'testSuite': return 'test-suites';
+    // Phase 10 (X2 CodeNode bridge): Code Node document type.
+    case 'codeNode': return 'code-nodes';
+    default: return null;
+  }
+}
+
+const ROOT_FILENAMES = {
+  manifest: 'manifest.json',
+  prd: 'prd.json',
+  tad: 'tad.json',
+  buildSequence: 'build-sequence.json',
+};
+
+/**
+ * Resolve an id like "REQ-002" to a path under rcf/.
+ *
+ * @param {string} id - canonical id, e.g. "REQ-002", "US-201", "FBS-003"
+ * @returns {{ kind: string, relPath: string } | null} null if the id pattern is unknown
+ */
+export function pathForId(id) {
+  if (typeof id !== 'string') return null;
+  if (id.startsWith('REQ-')) return { kind: 'req', relPath: `requirements/${id.toLowerCase()}.json` };
+  if (id.startsWith('US-')) return { kind: 'userStory', relPath: `user-stories/${id.toLowerCase()}.json` };
+  if (id.startsWith('TAC-')) return { kind: 'tac', relPath: `tacs/${id.toLowerCase()}.json` };
+  if (id.startsWith('ADR-')) return { kind: 'adr', relPath: `adrs/${id.toLowerCase()}.json` };
+  if (id.startsWith('FBS-')) return { kind: 'fbs', relPath: `fbs/${id.toLowerCase()}.json` };
+  if (id.startsWith('TS-')) return { kind: 'testSuite', relPath: `test-suites/${id.toLowerCase()}.json` };
+  // Phase 10 (X2 CodeNode bridge): Code Node document type.
+  if (id.startsWith('CN-')) return { kind: 'codeNode', relPath: `code-nodes/${id.toLowerCase()}.json` };
+  if (id === 'PRD-001' || id.startsWith('PRD-')) return { kind: 'prd', relPath: 'prd.json' };
+  if (id === 'TAD-001' || id.startsWith('TAD-')) return { kind: 'tad', relPath: 'tad.json' };
+  if (id === 'BS-001' || id.startsWith('BS-')) return { kind: 'buildSequence', relPath: 'build-sequence.json' };
+  return null;
+}
+
+/**
+ * Path for a known root document.
+ *
+ * @param {keyof typeof ROOT_FILENAMES} kind
+ * @returns {string}
+ */
+export function rootPathFor(kind) {
+  const name = ROOT_FILENAMES[kind];
+  if (!name) throw new TypeError(`Not a root kind: ${kind}`);
+  return name;
+}
+
+/**
+ * Read a file under the rcf root and parse JSON.
+ *
+ * @param {string} projectRoot - absolute path to project root
+ * @param {string} relPath - path relative to <projectRoot>/rcf/
+ * @returns {Promise<{ raw: string, doc: object } | import('../errors/index.js').RcfError>}
+ */
+async function readJson(projectRoot, relPath) {
+  const filePath = join(projectRoot, 'rcf', relPath);
+  let raw;
+  try {
+    raw = await readFile(filePath, 'utf8');
+  } catch (err) {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT') {
+      return rcfError({
+        kind: 'missingFile',
+        message: `File not found: rcf/${relPath}`,
+        filePath: `rcf/${relPath}`,
+      });
+    }
+    return rcfError({
+      kind: 'ioFailure',
+      message: `Failed to read file: ${/** @type {Error} */ (err).message}`,
+      filePath: `rcf/${relPath}`,
+    });
+  }
+  try {
+    const doc = JSON.parse(raw);
+    return { raw, doc };
+  } catch (err) {
+    return rcfError({
+      kind: 'parseFailure',
+      message: `JSON parse failed: ${/** @type {Error} */ (err).message}`,
+      filePath: `rcf/${relPath}`,
+    });
+  }
+}
+
+/**
+ * Load and validate one document by id.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.id
+ * @returns {Promise<{ doc: object, raw: string, kind: string, filePath: string } | import('../errors/index.js').RcfError>}
+ */
+export async function loadDocument({ projectRoot, id }) {
+  const resolved = pathForId(id);
+  if (!resolved) {
+    return rcfError({
+      kind: 'usage',
+      message: `Unrecognised document id: ${id}`,
+      documentId: id,
+    });
+  }
+  const result = await readJson(projectRoot, resolved.relPath);
+  if ('kind' in result && 'message' in result) {
+    const err = /** @type {import('../errors/index.js').RcfError} */ (result);
+    return { ...err, documentId: id };
+  }
+  const { doc, raw } = result;
+  const validationError = validateDocument({
+    doc,
+    kind: resolved.kind,
+    filePath: `rcf/${resolved.relPath}`,
+  });
+  if (validationError) {
+    // B5 (post-write validation): the parsed body rides along on the
+    // error so the walker can keep schema-invalid documents addressable
+    // (tree.invalidDocs) - a wedged doc must stay repairable/deletable.
+    return { ...validationError, documentId: id, doc, raw };
+  }
+  return { doc, raw, kind: resolved.kind, filePath: `rcf/${resolved.relPath}` };
+}
+
+/**
+ * Enumerate every `*.json` filename under `rcf/<subdir>/`, sorted. Not a
+ * discovery mechanism for tree topology (topology comes from parent-id
+ * fields); this is just the load-time enumeration required to bring every
+ * on-disk file into memory. Callers derive the document id from the
+ * filename stem in upper case (per the layout convention).
+ *
+ * Returns `{ files: string[] }` on success. Missing subdir returns
+ * `{ files: [] }` (an empty children collection is a valid tree state).
+ * IO failure returns `{ error: RcfError }`.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.subdir - subdir under `rcf/`, e.g. `requirements`
+ * @returns {Promise<{ files: string[] } | { error: import('../errors/index.js').RcfError }>}
+ */
+export async function listSubdirJsonFiles({ projectRoot, subdir }) {
+  let entries;
+  try {
+    entries = await readdir(join(projectRoot, 'rcf', subdir));
+  } catch (err) {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT') {
+      return { files: [] };
+    }
+    return {
+      error: rcfError({
+        kind: 'ioFailure',
+        message: `Failed to read directory: ${/** @type {Error} */ (err).message}`,
+        filePath: `rcf/${subdir}`,
+      }),
+    };
+  }
+  const files = entries.filter((e) => e.endsWith('.json')).sort();
+  return { files };
+}
+
+/**
+ * Load and validate a root document (manifest / prd / tad / buildSequence).
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {keyof typeof ROOT_FILENAMES} args.kind
+ * @returns {Promise<{ doc: object, raw: string, kind: string, filePath: string } | import('../errors/index.js').RcfError>}
+ */
+export async function loadRootDocument({ projectRoot, kind }) {
+  const relPath = rootPathFor(kind);
+  const result = await readJson(projectRoot, relPath);
+  if ('kind' in result && 'message' in result) {
+    return /** @type {import('../errors/index.js').RcfError} */ (result);
+  }
+  const { doc, raw } = result;
+  const validationError = validateDocument({
+    doc,
+    kind,
+    filePath: `rcf/${relPath}`,
+  });
+  // B5: parsed body rides along on validation errors (see loadDocument).
+  if (validationError) return { ...validationError, doc, raw };
+  return { doc, raw, kind, filePath: `rcf/${relPath}` };
+}