rcf-lite 0.8.0 → 0.9.0

package/src/core/store/ids.js

@@ -1,25 +1,175 @@
-// 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.
+// Id normalisation + family grammar. This module owns THE grammar for
+// RCF document ids: schema-family membership, filename-stem -> canonical-id
+// inversion, and family -> tree location. The walker (walker.js), the
+// document loader (loader.js) and the blueprint namespace helpers
+// (src/blueprint/namespace.js) all consume the primitives defined here so
+// the regexes live in exactly one place.
 //
-// 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.
+// Two schema families, per @stravica-ai/rcf-schemas 0.4.4 (see
+// docs/id-conventions.md):
 //
-// Normalisation is per hyphen-delimited segment and only touches
-// segments that are entirely digits:
+//  - Prefix families (REQ, US, PRD, BS, TAD, TS) admit an optional
+//    lowercase kebab-slug PREFIX joined by `-` to the family prefix.
+//    `REQ-001` under blueprint `spa` becomes `spa-REQ-001`.
+//    Schema pattern (common.reqId etc.):
+//      ^([a-z][a-z0-9]*(?:-[a-z0-9]+)*-)?<PREFIX>-\d{3,}$
 //
-//   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)
+//  - Suffix families (ADR, TAC, FBS, CN) admit an optional lowercase
+//    kebab-slug SUFFIX joined by `-` to the numeric tail. `ADR-005`
+//    under blueprint `spa` becomes `ADR-005-spa`.
+//    Schema pattern (common.adrId etc.):
+//      ^<PREFIX>-\d{3,}(-[a-z0-9]+(?:-[a-z0-9]+)*)?$
 //
-// 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`.
+//  - Unnamespaced families (AC, TC) live inline under their parent
+//    documents and never appear as top-level files under rcf/.
+//
+// The RCF id patterns admit a variable-width numeric run
+// (`^REQ-\d{3,}$`, `^AC-\d{3,}(-\d+)?$`, ...), so `REQ-001` and
+// `REQ-0001` are BOTH legal and BOTH name requirement number 1.
+// `normaliseId` / `sameId` collapse those spellings for the walker's
+// `globallyUniqueIds` rule and the writer's id allocator; that identity
+// pass runs independently of the family grammar above.
+
+// ---------------------------------------------------------------------------
+// Family membership (the single source for downstream re-exports)
+// ---------------------------------------------------------------------------
+
+export const PREFIX_FAMILIES = Object.freeze(['REQ', 'US', 'PRD', 'BS', 'TAD', 'TS']);
+export const SUFFIX_FAMILIES = Object.freeze(['ADR', 'TAC', 'FBS', 'CN']);
+export const UNNAMESPACED_FAMILIES = Object.freeze(['AC', 'TC']);
+
+export const PREFIX_FAMILY_SET = new Set(PREFIX_FAMILIES);
+export const SUFFIX_FAMILY_SET = new Set(SUFFIX_FAMILIES);
+export const UNNAMESPACED_FAMILY_SET = new Set(UNNAMESPACED_FAMILIES);
+
+export const SLUG_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+// Precompiled per-family regexes. Prefix families are anchored so the
+// optional slug prefix is captured cleanly; suffix families capture the
+// optional slug suffix. Suffix families are consulted first because they
+// never carry a leading slug -- see parseIdParts.
+const PREFIX_REGEXES = new Map();
+for (const family of PREFIX_FAMILIES) {
+  PREFIX_REGEXES.set(family, new RegExp(`^(?:([a-z][a-z0-9]*(?:-[a-z0-9]+)*)-)?${family}-(\\d{3,})$`));
+}
+const SUFFIX_REGEXES = new Map();
+for (const family of SUFFIX_FAMILIES) {
+  SUFFIX_REGEXES.set(family, new RegExp(`^${family}-(\\d{3,})(?:-([a-z0-9]+(?:-[a-z0-9]+)*))?$`));
+}
+const UNNAMESPACED_REGEXES = new Map([
+  ['AC', /^AC-(\d{3,})(?:-(\d+))?$/],
+  ['TC', /^TC-(\d{3,})-([a-z0-9-]+)$/],
+]);
+
+// Lowercase counterparts for stem-to-canonical inversion. Filenames on
+// disk are lower-case kebab (blueprint apply -> destPathFor -> toLowerCase),
+// and the same lowercase pattern is what the CLI init writer produces.
+const PREFIX_STEM_REGEXES = new Map();
+for (const family of PREFIX_FAMILIES) {
+  PREFIX_STEM_REGEXES.set(family, new RegExp(`^(?:([a-z][a-z0-9]*(?:-[a-z0-9]+)*)-)?${family.toLowerCase()}-(\\d{3,})$`));
+}
+const SUFFIX_STEM_REGEXES = new Map();
+for (const family of SUFFIX_FAMILIES) {
+  SUFFIX_STEM_REGEXES.set(family, new RegExp(`^${family.toLowerCase()}-(\\d{3,})(?:-([a-z0-9]+(?:-[a-z0-9]+)*))?$`));
+}
+
+// Family -> tree location. Root families (PRD/TAD/BS) live at rcf/ root
+// as single files; child families live one per JSON file under a subdir;
+// AC/TC live inline under their parents and never resolve to a top-level
+// file, so their entry is absent.
+const FAMILY_TO_LOCATION = new Map([
+  ['REQ', { kind: 'req', subdir: 'requirements', rootFile: null }],
+  ['US', { kind: 'userStory', subdir: 'user-stories', rootFile: null }],
+  ['TAC', { kind: 'tac', subdir: 'tacs', rootFile: null }],
+  ['ADR', { kind: 'adr', subdir: 'adrs', rootFile: null }],
+  ['FBS', { kind: 'fbs', subdir: 'fbs', rootFile: null }],
+  ['TS', { kind: 'testSuite', subdir: 'test-suites', rootFile: null }],
+  ['CN', { kind: 'codeNode', subdir: 'code-nodes', rootFile: null }],
+  ['PRD', { kind: 'prd', subdir: null, rootFile: 'prd.json' }],
+  ['TAD', { kind: 'tad', subdir: null, rootFile: 'tad.json' }],
+  ['BS', { kind: 'buildSequence', subdir: null, rootFile: 'build-sequence.json' }],
+]);
+
+// ---------------------------------------------------------------------------
+// Family grammar
+// ---------------------------------------------------------------------------
+
+/**
+ * Split an id into { family, prefixSlug, digits, suffixSlug }. Returns
+ * null when the id matches no known family pattern. The public blueprint
+ * surface (`src/blueprint/namespace.js`) re-exports this so callers keep
+ * a single import path even though the grammar lives here.
+ *
+ * @param {unknown} id
+ * @returns {{ family: string, prefixSlug: string|null, digits: string, suffixSlug: string|null } | null}
+ */
+export function parseIdParts(id) {
+  if (typeof id !== 'string' || id.length === 0) return null;
+  for (const [family, regex] of SUFFIX_REGEXES) {
+    const match = id.match(regex);
+    if (match) return { family, prefixSlug: null, digits: match[1], suffixSlug: match[2] ?? null };
+  }
+  for (const [family, regex] of PREFIX_REGEXES) {
+    const match = id.match(regex);
+    if (match) return { family, prefixSlug: match[1] ?? null, digits: match[2], suffixSlug: null };
+  }
+  for (const [family, regex] of UNNAMESPACED_REGEXES) {
+    const match = id.match(regex);
+    if (match) return { family, prefixSlug: null, digits: match[1], suffixSlug: null };
+  }
+  return null;
+}
+
+/**
+ * Location of a family in the rcf/ tree, or null when the family is not
+ * addressable as a top-level file (AC / TC).
+ *
+ * @param {string} family
+ * @returns {{ kind: string, subdir: string|null, rootFile: string|null } | null}
+ */
+export function familyLocation(family) {
+  return FAMILY_TO_LOCATION.get(family) ?? null;
+}
+
+/**
+ * Canonicalise a lowercase filename stem to its id form: upper-case ONLY
+ * the family segment, leaving any slug prefix / suffix verbatim (they are
+ * lower-case kebab by schema construction, matching the on-disk stem).
+ *
+ * Understands both id families:
+ *   spa-req-001         -> spa-REQ-001    (prefix family, slug 'spa')
+ *   req-001             -> REQ-001        (prefix family, no slug)
+ *   adr-005-spa         -> ADR-005-spa    (suffix family, slug 'spa')
+ *   adr-005             -> ADR-005        (suffix family, no slug)
+ *   fbs-004-user-login  -> FBS-004-user-login
+ *
+ * Returns null when the stem matches no known family pattern; the walker
+ * folds defensively in that case so an unrecognised stem surfaces via the
+ * downstream load error, not a crash.
+ *
+ * @param {unknown} stem
+ * @returns {string|null}
+ */
+export function canonicaliseStem(stem) {
+  if (typeof stem !== 'string' || stem.length === 0) return null;
+  // Suffix families first (mirrors parseIdParts: they never carry a
+  // leading slug, so their prefix segment is unambiguous).
+  for (const [family, regex] of SUFFIX_STEM_REGEXES) {
+    const match = stem.match(regex);
+    if (match) return match[2] ? `${family}-${match[1]}-${match[2]}` : `${family}-${match[1]}`;
+  }
+  for (const [family, regex] of PREFIX_STEM_REGEXES) {
+    const match = stem.match(regex);
+    if (match) return match[1] ? `${match[1]}-${family}-${match[2]}` : `${family}-${match[2]}`;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Numeric identity (leading-zero-tolerant). Independent of the family
+// grammar above -- REQ-001 and REQ-0001 are one id whether or not the
+// blueprint machinery is in play.
+// ---------------------------------------------------------------------------
 
 /**
  * Strip leading zeros from a run of digits without going through Number

package/src/core/store/loader.js

@@ -9,6 +9,7 @@ import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { rcfError } from '../errors/index.js';
+import { familyLocation, parseIdParts } from './ids.js';
 import { validateDocument } from './validator.js';
 
 /**
@@ -41,25 +42,35 @@ const ROOT_FILENAMES = {
 };
 
 /**
- * Resolve an id like "REQ-002" to a path under rcf/.
+ * Resolve an id like "REQ-002" (or a blueprint-namespaced id like
+ * "spa-REQ-001" / "ADR-005-spa") 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
+ * The id grammar lives in `./ids.js` (`parseIdParts` / `familyLocation`);
+ * this function is the read-side application of it. Prefix-family ids
+ * (REQ / US / PRD / BS / TAD / TS) may carry a leading slug namespace;
+ * suffix-family ids (ADR / TAC / FBS / CN) may carry a trailing slug
+ * namespace. Either way the filename on disk is the lower-cased id
+ * (blueprint apply's `destPathFor` writes it that way; the CLI writer
+ * matches).
+ *
+ * Returns null when the id matches no known family pattern OR when the
+ * family has no top-level file (AC and TC live inline under their
+ * parent US / TS).
+ *
+ * @param {string} id - canonical id, e.g. "REQ-002", "spa-REQ-001", "ADR-005-spa"
+ * @returns {{ kind: string, relPath: string } | null}
  */
 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;
+  const parts = parseIdParts(id);
+  if (!parts) return null;
+  const loc = familyLocation(parts.family);
+  if (!loc) return null;
+  // Root families (PRD / TAD / BS) resolve to their single root file.
+  if (loc.rootFile) return { kind: loc.kind, relPath: loc.rootFile };
+  // Child families resolve to <subdir>/<lower(id)>.json. AC / TC have no
+  // subdir entry and fall through to null via `!loc` above.
+  if (!loc.subdir) return null;
+  return { kind: loc.kind, relPath: `${loc.subdir}/${id.toLowerCase()}.json` };
 }
 
 /**

package/src/core/store/walker.js

@@ -16,30 +16,42 @@
 // `dependentsByFbsId`, `tsByAcId`, `tcsByAcId`, `usByTacId`.
 
 import { rcfError } from '../errors/index.js';
-import { normaliseId } from './ids.js';
+import { canonicaliseStem, normaliseId } from './ids.js';
 import { listSubdirJsonFiles, loadDocument, loadRootDocument, pathForId, subdirFor } from './loader.js';
 import { validateDocument } from './validator.js';
 
 /**
- * Derive an id from a filename stem, upper-casing the prefix segment only
- * and leaving any slug tail verbatim (0.8.0 slug-train; w-2026-07-28-012
- * landmine 1). Every id shape rcf-schemas 0.4.3 admits is
- * `<PREFIX>-<digits>[-<lower-kebab>]`, so the split is always on the
- * FIRST hyphen. Segments after the first hyphen are lower-case by
- * construction (schema pattern `[a-z0-9]+(?:-[a-z0-9]+)*`); we still
- * leave them verbatim rather than round-tripping through
- * .toLowerCase() so a slug that fails the pattern surfaces as-is at the
- * schema-validation step instead of being silently masked here.
+ * Derive an id from a filename stem. Delegates to the core grammar in
+ * `ids.js` (`canonicaliseStem`), which understands BOTH id families
+ * (rcf-schemas 0.4.4):
  *
- * @param {string} stem - filename stem, e.g. `fbs-004-user-login`.
- * @returns {string} canonical id, e.g. `FBS-004-user-login`.
+ *   - Prefix families (REQ / US / PRD / BS / TAD / TS) admit an optional
+ *     kebab-slug PREFIX -- `spa-req-001` -> `spa-REQ-001`.
+ *   - Suffix families (ADR / TAC / FBS / CN) admit an optional kebab-slug
+ *     SUFFIX -- `fbs-004-user-login` -> `FBS-004-user-login`,
+ *     `adr-005-spa` -> `ADR-005-spa`.
+ *
+ * Before this delegation the walker upper-cased only the FIRST dash
+ * segment, which was correct for suffix families but yielded
+ * `SPA-req-001` for a prefix-family stem `spa-req-001`. That id then
+ * failed `pathForId` at load time and every consuming verb refused with
+ * "Unrecognised document id" (w-2026-08-19-003).
+ *
+ * Defensive fallback: for stems that match no family pattern (a
+ * genuinely garbage filename), keep the old first-dash upper-case fold
+ * so the walker still records SOMETHING addressable and the subsequent
+ * load / validation step surfaces the real error. A crash here would
+ * hide the file's true problem.
+ *
+ * @param {string} stem - filename stem, e.g. `spa-req-001` or `fbs-004-user-login`.
+ * @returns {string} canonical id.
  */
 function idFromFilenameStem(stem) {
+  const canonical = canonicaliseStem(stem);
+  if (canonical) return canonical;
   const dash = stem.indexOf('-');
   if (dash === -1) return stem.toUpperCase();
-  const prefix = stem.slice(0, dash).toUpperCase();
-  const tail = stem.slice(dash);
-  return `${prefix}${tail}`;
+  return `${stem.slice(0, dash).toUpperCase()}${stem.slice(dash)}`;
 }
 
 /**

package/src/deployment/index.js

@@ -0,0 +1,13 @@
+// Deployment-gate barrel. Shared primitives downstream project probes
+// (TAC-210 external-service-dependency provisioning; TAC-211 core-flow
+// end-to-end) import so the placeholder-detection ruleset lives in ONE
+// place and extends via a rcf-lite minor bump, not a per-project fork.
+//
+// Watchpost first-production defect (w-2026-08-24-005, class cure
+// w-2026-08-24-006) is the reason this module exists: the app shipped
+// with RESEND_API_KEY set to a placeholder, the only login path was
+// inert, the gap was filed as a "quirk" note, and sign-off still said
+// DEPLOYED. The SPA blueprint v1.3.0 contributions bind those class
+// rules; this module is the shared enforcement handle.
+
+export { detectPlaceholderCredentialShape, PLACEHOLDER_DETECTOR_VERSION } from './placeholder-detector.js';

package/src/deployment/placeholder-detector.js

@@ -0,0 +1,113 @@
+// Canonical placeholder-credential-shape detector for the deployment-gate
+// class cure (spa-US-1132 / TAC-210, w-2026-08-24-006).
+//
+// The watchpost first production review (w-2026-08-24-005) shipped with
+// RESEND_API_KEY set to a placeholder value; the only login path (magic-link
+// email) was inert; sign-off still said DEPLOYED. The gap was filed as a
+// "quirk" note in status.md rather than blocked at gate time. This module
+// owns the one canonical placeholder shape catalogue rcf-lite ships so
+// downstream projects (via TAC-210 realisations) apply the same detector
+// - extending the ruleset is a rcf-lite minor bump, never a per-project
+// reinvention.
+//
+// The catalogue is deliberately narrow: only credential-shape strings a
+// developer would reasonably type as a stand-in ("YOUR_API_KEY_HERE",
+// "changeme", "xxx", empty). It does NOT try to classify all bad values;
+// entropy checks, provider-specific prefix rules, and format regexes live
+// in project-authored probes. This catalogue is what would have refused
+// the watchpost RESEND_API_KEY at gate time.
+
+/**
+ * @typedef {object} PlaceholderMatch
+ * @property {'empty'|'single-dash'|'null-token'|'you-here'|'named-stand-in'|'repeat-char'} pattern
+ *   The named pattern that matched. Callers surface this on their report
+ *   so a refusal message can name why.
+ */
+
+/**
+ * @typedef {object} PlaceholderVerdict
+ * @property {boolean} isPlaceholder     true when the value matches a placeholder shape
+ * @property {PlaceholderMatch['pattern']} [pattern]  the matched pattern name, when isPlaceholder is true
+ * @property {string} [reason]           a short refusal-message-ready reason string
+ */
+
+// Case-insensitive named stand-ins a developer would reasonably type. The
+// set is intentionally small; adding to it is a rcf-lite minor bump, and
+// the additions land in ONE place downstream projects inherit.
+const NAMED_STAND_INS = new Set([
+  'changeme',
+  'placeholder',
+  'example',
+  'test',
+  'dummy',
+  'fake',
+  'todo',
+  'tbd',
+  'sample',
+  'default',
+]);
+
+// `YOUR_X_HERE`, `your-key-here`, etc. Case-insensitive.
+const YOU_HERE_RE = /^your[_-].+[_-]here$/i;
+
+// Repeated single characters ("xxxx", "----", "0000") of length >= 3, or
+// the literal "xxx+" family common in scaffolds.
+const REPEAT_CHAR_RE = /^(.)\1{2,}$/;
+
+// Literal null-token strings that leak in when a resolver hands back a
+// nullish value stringified. `.env` files stringify unset values to the
+// empty string, but a JS resolver that String()s an undefined lands
+// "undefined" in the ship environment - that IS a placeholder, not a
+// live credential.
+const NULL_TOKENS = new Set(['null', 'undefined', 'none']);
+
+/**
+ * Detect whether `value` matches a placeholder-shape a credential value
+ * would never legitimately hold. Deterministic; case-insensitive against
+ * the named-stand-in catalogue and the `YOUR_X_HERE` pattern.
+ *
+ * The intent is a hard refusal filter, not a heuristic: every match is
+ * something a developer typed as a stand-in and forgot to replace. False
+ * positives are vanishingly unlikely; the shortest name-family entry is
+ * six characters ("dummy" being five is the shortest, and no real credential
+ * is a five-character English word); the repeat-char rule requires length
+ * >= 3 so a two-character hash prefix does not match.
+ *
+ * @param {unknown} value  the raw credential-field value at ship time
+ * @returns {PlaceholderVerdict}
+ */
+export function detectPlaceholderCredentialShape(value) {
+  // Non-strings are not credentials the shipped runtime carries; skip.
+  if (typeof value !== 'string') {
+    return { isPlaceholder: false };
+  }
+  const raw = value;
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    return { isPlaceholder: true, pattern: 'empty', reason: 'empty or whitespace-only credential value' };
+  }
+  if (trimmed === '-' || trimmed === '_') {
+    return { isPlaceholder: true, pattern: 'single-dash', reason: `credential value is the single-character stand-in "${trimmed}"` };
+  }
+  const lower = trimmed.toLowerCase();
+  if (NULL_TOKENS.has(lower)) {
+    return { isPlaceholder: true, pattern: 'null-token', reason: `credential value is the literal null-token string "${trimmed}"` };
+  }
+  if (YOU_HERE_RE.test(trimmed)) {
+    return { isPlaceholder: true, pattern: 'you-here', reason: `credential value matches the YOUR_X_HERE scaffold pattern: "${trimmed}"` };
+  }
+  if (NAMED_STAND_INS.has(lower)) {
+    return { isPlaceholder: true, pattern: 'named-stand-in', reason: `credential value is the named stand-in "${trimmed}"` };
+  }
+  if (REPEAT_CHAR_RE.test(trimmed)) {
+    return { isPlaceholder: true, pattern: 'repeat-char', reason: `credential value is a repeated-single-character stand-in "${trimmed}"` };
+  }
+  return { isPlaceholder: false };
+}
+
+/**
+ * The catalogue's stable identifier. Downstream probes surface this on
+ * their report so the gate-failure trail names which detector version
+ * refused the value. Extending the catalogue bumps this constant.
+ */
+export const PLACEHOLDER_DETECTOR_VERSION = '1.0.0';

package/src/query/formatters/table.js

@@ -122,7 +122,7 @@ function formatTraceTable(result) {
     lines.push(`${directionLabel}: (none)`);
   } else {
     for (const n of showList) {
-      rows.push([String(n.depth), n.id, n.kind, cellTitle(n.id)]);
+      rows.push([String(n.depth), n.id, n.kind, n.title ?? '']);
     }
     lines.push(renderTable(rows));
   }
@@ -139,7 +139,7 @@ function formatBothTraceTable(result) {
     lines.push('  (none)');
   } else {
     const rows = [['Depth', 'Id', 'Kind', 'Title']];
-    for (const n of ancestors) rows.push([String(n.depth), n.id, n.kind, '']);
+    for (const n of ancestors) rows.push([String(n.depth), n.id, n.kind, n.title ?? '']);
     lines.push(renderTable(rows));
   }
   lines.push('');
@@ -151,7 +151,7 @@ function formatBothTraceTable(result) {
     lines.push('  (none)');
   } else {
     const rows = [['Depth', 'Id', 'Kind', 'Title']];
-    for (const n of descendants) rows.push([String(n.depth), n.id, n.kind, '']);
+    for (const n of descendants) rows.push([String(n.depth), n.id, n.kind, n.title ?? '']);
     lines.push(renderTable(rows));
   }
   return `${lines.join('\n')}\n`;
@@ -194,10 +194,7 @@ function renderTable(rows) {
   return [out[0], sep, ...out.slice(1)].join('\n');
 }
 
-// Placeholder for future title lookup - the pure trace result does not
-// carry doc bodies, so title columns render blank unless the caller
-// passes a title source. Left here for the trace `Title` column so the
-// column stays if we ever wire in a title map without a schema change.
-function cellTitle(_id) {
-  return '';
-}
+// Trace nodes carry `title` as of the paper-cut batch (previously the
+// Title column was always empty). Doc-kind title source: PRD →
+// productName, REQ/US/TAC/ADR/TAD/TS/FBS/CN → title, inline AC/TC →
+// description. Nodes lacking a title render blank.

package/src/query/trace.js

@@ -32,6 +32,7 @@
  * @property {string} id
  * @property {string} kind
  * @property {number} depth - 0 for pivot; positive for descendants; negative for ancestors
+ * @property {string} title - display title, or '' when the node has none
  */
 
 /**
@@ -71,6 +72,41 @@ export function kindOf(tree, id) {
   return null;
 }
 
+/**
+ * Return the display title for an id, or '' when the node carries none.
+ * Different doc kinds carry the title on different fields (PRD →
+ * productName; inline AC/TC → description; everything else → title). A
+ * standalone doc that lacks its title field renders blank rather than
+ * throwing; that keeps trace output readable on a partially-authored tree.
+ *
+ * Inline lookup: AC / TC nodes live inside their parent's inline array
+ * (userStory.acceptanceCriteria[] / testSuite.testCases[]), not as
+ * standalone entries in `tree.byId`. Resolve via parentByChild.
+ *
+ * @param {object} tree - walker TreeModel
+ * @param {string} id
+ * @param {string} kind - as returned by `kindOf`
+ * @returns {string}
+ */
+export function titleOf(tree, id, kind) {
+  if (kind === 'ac') {
+    const usId = tree.parentByChild.get(id);
+    const us = usId ? tree.byId.get(usId) : null;
+    const ac = us?.acceptanceCriteria?.find((a) => a?.id === id);
+    return ac?.description ?? '';
+  }
+  if (kind === 'tc') {
+    const tsId = tree.parentByChild.get(id);
+    const ts = tsId ? tree.byId.get(tsId) : null;
+    const tc = ts?.testCases?.find((t) => t?.id === id);
+    return tc?.description ?? '';
+  }
+  const doc = tree.byId.get(id);
+  if (!doc) return '';
+  if (kind === 'prd') return doc.productName ?? '';
+  return doc.title ?? '';
+}
+
 /**
  * Compute a trace from `id` in the requested direction. Unknown pivot
  * returns `{found: false}`; the handler layer converts this to exit 2.
@@ -134,7 +170,7 @@ export function computeTrace(tree, {
  */
 function walkForward(tree, pivot, pivotKind, includeCode = false, expandFbsDependents = false) {
   /** @type {TraceNode[]} */
-  const nodes = [{ id: pivot, kind: pivotKind, depth: 0 }];
+  const nodes = [{ id: pivot, kind: pivotKind, depth: 0, title: titleOf(tree, pivot, pivotKind) }];
   /** @type {TraceEdge[]} */
   const edges = [];
   const seen = new Set([pivot]);
@@ -158,7 +194,12 @@ function walkForward(tree, pivot, pivotKind, includeCode = false, expandFbsDepen
       if (!childKind) continue;
       const nextDepth = curDepth + 1;
       depthById.set(child.id, nextDepth);
-      nodes.push({ id: child.id, kind: childKind, depth: nextDepth });
+      nodes.push({
+        id: child.id,
+        kind: childKind,
+        depth: nextDepth,
+        title: titleOf(tree, child.id, childKind),
+      });
       queue.push(child.id);
     }
   }
@@ -178,7 +219,7 @@ function walkForward(tree, pivot, pivotKind, includeCode = false, expandFbsDepen
  */
 function walkBack(tree, pivot, pivotKind) {
   /** @type {TraceNode[]} */
-  const nodes = [{ id: pivot, kind: pivotKind, depth: 0 }];
+  const nodes = [{ id: pivot, kind: pivotKind, depth: 0, title: titleOf(tree, pivot, pivotKind) }];
   /** @type {TraceEdge[]} */
   const edges = [];
   const seen = new Set([pivot]);
@@ -188,7 +229,7 @@ function walkBack(tree, pivot, pivotKind) {
     const k = kindOf(tree, toId);
     if (!k) return;
     seen.add(toId);
-    nodes.push({ id: toId, kind: k, depth });
+    nodes.push({ id: toId, kind: k, depth, title: titleOf(tree, toId, k) });
     edges.push({ from: fromId, to: toId, kind: edgeKind });
   };