rcf-lite 0.7.1 → 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` };
 }
 
 /**
@@ -154,7 +165,10 @@ export async function loadDocument({ projectRoot, id }) {
  * 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).
+ * filename stem by upper-casing the PREFIX segment only (0.8.0
+ * slug-train, w-2026-07-28-012 landmine 1); slug tails stay verbatim
+ * because rcf-schemas 0.4.3 admits lower-case kebab tails on FBS / CN /
+ * ADR / TAC and a full-stem fold would silently detach the graph.
  *
  * Returns `{ files: string[] }` on success. Missing subdir returns
  * `{ files: [] }` (an empty children collection is a valid tree state).

package/src/core/store/walker.js

@@ -16,10 +16,44 @@
 // `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. Delegates to the core grammar in
+ * `ids.js` (`canonicaliseStem`), which understands BOTH id families
+ * (rcf-schemas 0.4.4):
+ *
+ *   - 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();
+  return `${stem.slice(0, dash).toUpperCase()}${stem.slice(dash)}`;
+}
+
 /**
  * @typedef {object} TreeModel
  * @property {object|null} manifest
@@ -182,7 +216,23 @@ async function loadChildKind(kind, { projectRoot, tree, errors }) {
   }
   for (const entry of listing.files) {
     const stem = entry.replace(/\.json$/, '');
-    const id = stem.toUpperCase();
+    // 0.8.0 slug-train (w-2026-07-28-012 landmine 1 / d-2026-07-28-011
+    // recon): upper-case the PREFIX segment only. Full-stem toUpperCase
+    // was lossless while every id was `<PREFIX>-<digits>`; the moment a
+    // slug lands (`fbs-004-user-login.json` -> body `FBS-004-user-login`),
+    // the whole-stem fold produced `FBS-004-USER-LOGIN` in tree.byId /
+    // kindById / parentByChild while every inbound reference
+    // (dependsOnFbsIds, contextRequirements.adrIds, us.tacIds,
+    // cn.dependencies) used the lower-case form. The graph silently
+    // detached. Fixing this here, before any slug-consuming change lands,
+    // is the single load-bearing precondition of the whole slug design
+    // (see the item's regression test in test/store/walker.test.js:
+    // "walkTree preserves case on slug tails when deriving id from
+    // filename"). Slugs are lower-case kebab by construction (rcf-schemas
+    // 0.4.3 pattern `[a-z0-9]+(?:-[a-z0-9]+)*`), so leaving the tail
+    // verbatim is safe. `PRD-001.json` / `req-002.json` / mixed-case
+    // filenames continue to normalise their prefix.
+    const id = idFromFilenameStem(stem);
     // Filename-derived ids are not injective: on a case-sensitive
     // filesystem `REQ-001.json` and `req-001.json` are two files that
     // both resolve to `REQ-001`. Recording both silently collapsed the
@@ -848,10 +898,18 @@ function collectBrokenReferences(tree, errors) {
       }
     }
     // Inline TC id pattern check: `TC-<TS-suffix>-<slug>`.
-    const tsSuffix = ts.id?.match(/^TS-(\d{3})$/)?.[1];
+    // 0.8.0 slug-train (w-2026-07-28-012 landmine 3): widened from
+    // `\d{3}` (three-digit-exact) to `\d{3,}` in lockstep with
+    // rcf-schemas 0.4.3's TS/TC pattern widening. The pre-0.8.0 shape
+    // silently skipped every TS above 999: a TS-1000 failed the exact
+    // three-digit match, tsSuffix was undefined, and the whole
+    // idPrefixMatchesParent rule never fired for that TS's inline TCs.
+    // No error, no warning, just an unchecked doc -- exactly the
+    // silent-skip class this train is chartered to eliminate.
+    const tsSuffix = ts.id?.match(/^TS-(\d{3,})$/)?.[1];
     if (tsSuffix) {
       for (const tc of ts.testCases ?? []) {
-        const m = String(tc.id ?? '').match(/^TC-(\d{3})-[a-z0-9-]+$/);
+        const m = String(tc.id ?? '').match(/^TC-(\d{3,})-[a-z0-9-]+$/);
         if (m && m[1] !== tsSuffix) {
           errors.push(rcfError({
             kind: 'brokenReference',

package/src/core/store/writer.js

@@ -249,7 +249,9 @@ export function nextIdForKind(tree, kind, opts = {}) {
       if (typeof slug !== 'string' || slug.length === 0) {
         throw new TypeError('nextIdForKind tc requires opts.slug');
       }
-      const mTs = /^TS-(\d{3})$/.exec(tsId);
+      // 0.8.0 slug-train (w-2026-07-28-012 landmine 3): widened to
+      // `\d{3,}` in lockstep with rcf-schemas 0.4.3.
+      const mTs = /^TS-(\d{3,})$/.exec(tsId);
       if (!mTs) throw new TypeError('nextIdForKind tc: unrecognised TS id');
       return `TC-${mTs[1]}-${slug}`;
     }
@@ -263,15 +265,24 @@ export function nextIdForKind(tree, kind, opts = {}) {
 // set fed in (see `occupiedIdsOfKind`). Comparison stays numeric and the
 // emitted id is always the canonical three-digit-minimum spelling, so a
 // freshly allocated id is never a leading-zero variant of a taken one.
+//
+// 0.8.0 slug-train (w-2026-07-28-012 landmine 2): the previous shape used
+// `^<PREFIX>-(\\d+)$` and slug-blindly ignored any id whose number was
+// followed by a slug tail. Verified empirically: /^FBS-(\d+)$/.test(
+// 'FBS-003-user-login') === false, so a slugged id was invisible to the
+// high-water mark and the allocator reset to 001 and re-issued taken
+// numbers. Use the shared `idNumber(id, prefix)` helper (ids.js:72-78,
+// pattern `^${prefix}-(\d+)(?:-|$)`) instead of writing a second parser
+// -- that helper's whole job is to parse a number out of any id shape the
+// schemas admit (numeric-only OR slug-suffixed), so numeric-only and
+// slugged ids feed into the SAME high-water mark and cannot collide by
+// spelling. w-2026-07-28-017's `occupiedIdsOfKind` already feeds the
+// right ids in; landmine 2 is that this reader could not parse them.
 function nextFlatId(prefix, ids) {
   let max = 0;
-  const re = new RegExp(`^${prefix}-(\\d+)$`);
   for (const id of ids) {
-    const m = re.exec(id ?? '');
-    if (m) {
-      const n = Number(m[1]);
-      if (n > max) max = n;
-    }
+    const n = idNumber(id, prefix);
+    if (n !== null && n > max) max = n;
   }
   return `${prefix}-${String(max + 1).padStart(3, '0')}`;
 }
@@ -904,8 +915,14 @@ async function createInlineTc({ projectRoot, tree, options, body, walkErrors = [
       message: 'create tc: --test-pointer is required (format filePath::testName; coverage counts a TC only when its pointer resolves to a real test)',
     });
   }
-  const slug = options.slug ?? deriveSlug(description);
-  const tsSuffix = /^TS-(\d{3})$/.exec(parentTsId)?.[1];
+  // 0.8.0 slug-train (w-2026-07-28-012 landmine 4): deriveSlug now returns
+  // '' on empty derivation so the TC-specific `|| 'tc'` fallback is applied
+  // here rather than leaking the literal 'tc' into non-TC callers. See
+  // deriveSlug for the full argument.
+  const slug = options.slug ?? (deriveSlug(description) || 'tc');
+  // 0.8.0 slug-train (w-2026-07-28-012 landmine 3): widened `\d{3}` ->
+  // `\d{3,}` in lockstep with rcf-schemas 0.4.3.
+  const tsSuffix = /^TS-(\d{3,})$/.exec(parentTsId)?.[1];
   if (!tsSuffix) {
     return rcfError({ kind: 'usage', message: `create tc: parent ${parentTsId} has an unrecognised id shape` });
   }
@@ -959,7 +976,17 @@ async function createInlineTc({ projectRoot, tree, options, body, walkErrors = [
  * partial word is dropped (B2 fix, E2E matrix 2026-07-06-003 - ids
  * like "...-saved-whil" chopped mid-word). A single unbroken word
  * longer than the limit keeps its 40-char prefix (no boundary exists).
+ *
+ * 0.8.0 slug-train (w-2026-07-28-012 landmine 4): returns '' when no
+ * slug can be derived (empty / non-word / whitespace input). The previous
+ * shape returned the literal 'tc' as a fallback, which leaked the TC
+ * kind-specific default into every slug caller -- an FBS whose title
+ * derived to empty would land as `FBS-004-tc`, entirely wrong for the
+ * kind. TC callers now apply `deriveSlug(description) || 'tc'` locally
+ * (createInlineTc); every non-TC caller decides what its own empty
+ * fallback should be, or refuses.
  * @param {string} description
+ * @returns {string} slug, or '' when no slug can be derived
  */
 export function deriveSlug(description) {
   const full = String(description)
@@ -973,7 +1000,7 @@ export function deriveSlug(description) {
     if (boundary > 0) slug = slug.slice(0, boundary);
   }
   slug = slug.replace(/-+$/g, '');
-  return slug.length > 0 ? slug : 'tc';
+  return slug;
 }
 
 /**
@@ -1160,7 +1187,10 @@ function checkCrossLinks(tree, kind, doc, docId) {
 function resolveInlineId(id) {
   if (typeof id !== 'string') return null;
   if (/^AC-\d+(-\d+)?$/.test(id)) return { kind: 'ac' };
-  if (/^TC-\d{3}-[a-z0-9-]+$/.test(id)) return { kind: 'tc' };
+  // 0.8.0 slug-train (w-2026-07-28-012 landmine 3): widened `\d{3}` -> `\d{3,}`
+  // in lockstep with rcf-schemas 0.4.3. A TC-1000-... would otherwise fail
+  // the inline resolver even though the schema admits it.
+  if (/^TC-\d{3,}-[a-z0-9-]+$/.test(id)) return { kind: 'tc' };
   return null;
 }
 

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';