rcf-lite 0.8.0 → 0.10.0

package/src/cli/standards.js

@@ -0,0 +1,127 @@
+// `rcf standards <verb>` — Phase 1 landing (add | list).
+
+import { parseArgs } from 'node:util';
+
+import { isRcfError } from '#core/errors';
+import { walkTree } from '#core/store';
+import { findProjectRoot } from '../view/index.js';
+import { listStandards, registerStandardsPack } from '../blueprint/index.js';
+
+export const HELP = `Usage: rcf define standards <verb> [options]
+
+Verbs:
+  add <source>           Register a standards pack against the project.
+                         Reference-by-default: if <source> lives inside
+                         the project root, the pack is referenced in place
+                         and no copy is written. If <source> lives OUTSIDE
+                         the project root, the pack is copied into
+                         rcf/standards/<slug>/ so the tree stays portable.
+  list                   List every registered standards pack.
+
+Options (for add):
+  --slug <slug>              Required. Kebab slug for this pack.
+  --tags <t1,t2,...>         Required. Comma-separated tag vocabulary.
+  --summary <string>         Optional short summary read by the selective-
+                             retrieval step alongside the tags.
+  --tests-provided-by <val>  Required. One of: standard | agent | none.
+  --provenance <val>         Required. One of: personal | corporate.
+  --dry-run                  Print intended writes without executing.
+  --quiet                    Suppress non-error stdout.
+  --help                     Print this help.
+`;
+
+const OPTION_SPEC = {
+  slug: { type: 'string' },
+  tags: { type: 'string' },
+  summary: { type: 'string' },
+  'tests-provided-by': { type: 'string' },
+  provenance: { type: 'string' },
+  'dry-run': { type: 'boolean' },
+  quiet: { type: 'boolean' },
+  help: { type: 'boolean' },
+};
+
+/**
+ * @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: true, strict: true });
+  } catch (err) {
+    stderr.write(`[error] ${err.message}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  if (parsed.values.help || parsed.positionals.length === 0) {
+    stdout.write(HELP);
+    return 0;
+  }
+  const verb = parsed.positionals[0];
+  const rest = parsed.positionals.slice(1);
+
+  const projectRoot = await findProjectRoot(cwd);
+  if (!projectRoot) {
+    stderr.write('[error] no rcf/ tree found in this directory or any ancestor.\n');
+    return 2;
+  }
+  const { tree, errors } = await walkTree({ projectRoot });
+  if (errors.length > 0 && verb !== 'list') {
+    for (const e of errors) stderr.write(`[tree] ${e.kind}: ${e.message}\n`);
+    return 2;
+  }
+
+  if (verb === 'add') {
+    if (rest.length === 0) {
+      stderr.write('[error] standards add: missing <source>\n');
+      return 2;
+    }
+    if (!parsed.values.slug || !parsed.values.tags || !parsed.values['tests-provided-by'] || !parsed.values.provenance) {
+      stderr.write('[error] standards add: --slug, --tags, --tests-provided-by and --provenance are required\n');
+      return 2;
+    }
+    const result = await registerStandardsPack({
+      projectRoot, tree,
+      sourcePath: rest[0],
+      slug: parsed.values.slug,
+      tags: parsed.values.tags.split(',').map((t) => t.trim()).filter(Boolean),
+      summary: parsed.values.summary,
+      testsProvidedBy: parsed.values['tests-provided-by'],
+      provenance: parsed.values.provenance,
+      dryRun: parsed.values['dry-run'] === true,
+    });
+    if (isRcfError(result)) {
+      stderr.write(`[error] standards add: ${result.message}\n`);
+      return 2;
+    }
+    if (!parsed.values.quiet) {
+      const shape = result.copyPath ? `copied to ${result.copyPath}` : `referenced in place at ${result.entry.sourcePath}`;
+      const state = result.alreadyRegistered ? 'already registered (no change)' : 'registered';
+      stdout.write(`[standards] '${result.entry.slug}' ${state} (${shape}).\n`);
+    }
+    return 0;
+  }
+
+  if (verb === 'list') {
+    const rows = listStandards(tree);
+    if (rows.length === 0) {
+      if (!parsed.values.quiet) stdout.write('[standards] no standards packs registered on this project.\n');
+      return 0;
+    }
+    for (const row of rows) {
+      const shape = row.copyPath ? 'copied' : 'referenced';
+      stdout.write(`${row.slug}\t${row.testsProvidedBy}\t${row.provenance}\t${shape}\t${(row.tags ?? []).join(',')}\n`);
+    }
+    return 0;
+  }
+
+  stderr.write(`[error] standards: unknown verb '${verb}'\n`);
+  stderr.write(HELP);
+  return 2;
+}

package/src/cli/test-suite.js

@@ -34,7 +34,7 @@ const APPROVE_OPTION_SPEC = {
 
 const VALID_PROFILES = new Set(['mock', 'stub', 'fixture', 'live', 'mixed']);
 
-export const HELP = `Usage: rcf test-suite <ts-id> <verb> [options]
+export const HELP = `Usage: rcf build test-suite <ts-id> <verb> [options]
 
 Verbs:
   provenance                Author runtimeProvenance on the TS or a specific TC

package/src/cli/trace.js

@@ -29,7 +29,7 @@ const OPTION_SPEC = {
   'to-code': { type: 'boolean' },
 };
 
-export const HELP = `Usage: rcf trace <id|path> [options]
+export const HELP = `Usage: rcf audit trace <id|path> [options]
 
 Walk the graph from <id> forward (descendants), backward (ancestors),
 or both. Default is --forward. When <id> is not a known document id, it

package/src/cli/ui-baseline.js

@@ -48,7 +48,7 @@ const OPTION_SPEC = {
   help: { type: 'boolean' },
 };
 
-export const HELP = `Usage: rcf ui-baseline <verb> [options]
+export const HELP = `Usage: rcf discover ui-baseline <verb> [options]
 
 Manage the project's ruled UI defaults (theme, layout, contrast,
 components, auth flow). Written once per project as a uiBaseline record
@@ -136,7 +136,7 @@ export async function main(argv, deps = {}) {
 function runShow({ tree, stdout, flags }) {
   const record = tree.manifest?.uiBaseline;
   if (!record) {
-    stdout.write('ui-baseline: no baseline recorded. Run \'rcf ui-baseline init\'.\n');
+    stdout.write('ui-baseline: no baseline recorded. Run \'rcf discover ui-baseline init\'.\n');
     return 0;
   }
   if (flags.json) {
@@ -171,7 +171,7 @@ async function runOptOut({ tree, projectRoot, stdout, stderr, flags, now }) {
   }
   const normalisedField = flags.field.startsWith('defaults.') ? flags.field.slice('defaults.'.length) : flags.field;
   if (!isKnownBaselinePath(normalisedField)) {
-    stderr.write(`[error] usage ui-baseline opt-out: unknown baseline field '${normalisedField}' (see 'rcf ui-baseline show' for the field list)\n`);
+    stderr.write(`[error] usage ui-baseline opt-out: unknown baseline field '${normalisedField}' (see 'rcf discover ui-baseline show' for the field list)\n`);
     return 2;
   }
   const result = await writeUiBaselineOptOut({

package/src/cli/ui-classify.js

@@ -19,11 +19,11 @@ const OPTION_SPEC = {
   help: { type: 'boolean' },
 };
 
-export const HELP = `Usage: rcf ui-classify <fbs-id> [options]
+export const HELP = `Usage: rcf discover ui-classify <fbs-id> [options]
 
 Run the UI-bearing classifier on one FBS and print the verdict. Does
 not write to the FBS document; ratify with:
-  rcf update <fbs-id> --set uiBearing=true
+  rcf define update <fbs-id> --set uiBearing=true
 
 Options:
   --json                    Emit the uiClassification block as JSON.
@@ -98,9 +98,9 @@ export async function main(argv, deps = {}) {
     }
   }
   if (block.verdict === 'ui') {
-    stdout.write('  Ratify with: rcf update ' + fbsId + ' --set uiBearing=true\n');
+    stdout.write('  Ratify with: rcf define update ' + fbsId + ' --set uiBearing=true\n');
   } else if (block.verdict === 'notUi' && signals.length === 0) {
-    stdout.write('  No UI signals detected. Override with: rcf update ' + fbsId + ' --set uiBearing=true\n');
+    stdout.write('  No UI signals detected. Override with: rcf define update ' + fbsId + ' --set uiBearing=true\n');
   } else if (block.verdict === 'operatorOverride') {
     stdout.write('  Operator ruling recorded on FBS.uiBearing wins over the classifier.\n');
   }

package/src/cli/update.js

@@ -26,7 +26,7 @@ const OPTION_SPEC = {
   'derive-deps': { type: 'boolean' },
 };
 
-export const HELP = `Usage: rcf update <id> [options]
+export const HELP = `Usage: rcf define update <id> [options]
 
 Options:
   --set <dotPath>=<value>   Set a field; repeatable
@@ -80,7 +80,7 @@ export async function main(argv, deps = {}) {
   // update is gated on the POST-write tree state inside the writer, so
   // repairing a broken doc is exactly what this verb is now for.
   if (walkResult.errors.length > 0) {
-    stderr.write(`[warn] tree has ${walkResult.errors.length} pre-existing issue(s); proceeding - writes are validated against the post-write state (run 'rcf validate' for details)\n`);
+    stderr.write(`[warn] tree has ${walkResult.errors.length} pre-existing issue(s); proceeding - writes are validated against the post-write state (run 'rcf define validate' for details)\n`);
   }
 
   const sets = [];

package/src/cli/validate.js

@@ -18,7 +18,7 @@ const OPTION_SPEC = {
   'no-code': { type: 'boolean' },
 };
 
-export const HELP = `Usage: rcf validate [options]
+export const HELP = `Usage: rcf define validate [options]
 
 Walk the rcf/ tree and report schema-validation and broken-reference
 issues. Exits 0 when clean, 3 on issues.
@@ -140,7 +140,7 @@ export async function main(argv, deps = {}) {
   }
   if (errors.length === 0) {
     if (!flags.quiet) {
-      stdout.write('rcf validate: tree is clean.\n');
+      stdout.write('rcf define validate: tree is clean.\n');
       // B4 (E2E matrix 2026-07-06-003): scaffold TODO placeholders were
       // surviving to otherwise-valid trees unflagged. Non-blocking notice
       // only - the exit code is unchanged.

package/src/cli/view.js

@@ -24,7 +24,7 @@ import { parsePersistUntil } from '../view-supervisor/persist-until.js';
 export const DEFAULT_PORT = 4373;
 export const SHUTDOWN_BUDGET_MS = 2000;
 
-export const HELP = `Usage: rcf view [subverb] [options]
+export const HELP = `Usage: rcf audit view [subverb] [options]
 
 Serve the on-disk RCF tree as a live HTML review surface. Runs a
 long-running HTTP + SSE server on 127.0.0.1 that watches rcf/ and pushes
@@ -32,10 +32,10 @@ tree updates to the connected browser tab. No on-disk output; no static
 files are written.
 
 Subverbs (spec §9.2):
-  rcf view                  Foreground server (default; lifetime tied to
+  rcf audit view            Foreground server (default; lifetime tied to
                             the invoking session). Backward-compatible
                             with pre-0.7.0 callers.
-  rcf view start [--detach|--foreground] [--persist-until <duration|iso>]
+  rcf audit view start [--detach|--foreground] [--persist-until <duration|iso>]
                             Start the server. --detach forks a supervised
                             background process that persists across the
                             parent session's death; the manifest carries
@@ -50,12 +50,14 @@ Subverbs (spec §9.2):
                             --detach; non-interactive callers keep
                             --foreground so a script does not orphan a
                             process.
-  rcf view status [--json]  Print the supervisor state:
+  rcf audit view status [--json]
+                            Print the supervisor state:
                             running | stale | not-started.
-  rcf view stop             Send SIGTERM to the supervised process, wait
+  rcf audit view stop       Send SIGTERM to the supervised process, wait
                             for a clean shutdown, and clear the manifest
                             record.
-  rcf view logs [--tail <n>] Print the supervisor log tail (default 200).
+  rcf audit view logs [--tail <n>]
+                            Print the supervisor log tail (default 200).
 
 Options:
   --port <n>        Bind the HTTP server on the given port.
@@ -83,7 +85,7 @@ Security posture:
 Shutdown:
   Ctrl-C (SIGINT) or SIGTERM triggers a clean shutdown: watcher
   closed, SSE connections drained with a shutdown event, port
-  released, 2s force-exit budget. Detached: rcf view stop sends
+  released, 2s force-exit budget. Detached: rcf audit view stop sends
   SIGTERM to the supervisor and waits for a clean unwind.
 
 Exit codes:
@@ -213,7 +215,7 @@ export function maybeAutoOpen({ target, noOpen, stream, env, stderr, spawnFn = s
 }
 
 /**
- * Main entry for the `rcf view` subcommand. Mirrors the shape of the
+ * Main entry for the `rcf audit view` subcommand. Mirrors the shape of the
  * old bin/rcf-view.js main().
  *
  * @param {string[]} argv - the argv slice *after* the "view" positional
@@ -278,7 +280,7 @@ export async function main(argv, deps = {}) {
     });
   } catch (err) {
     if (/** @type {NodeJS.ErrnoException} */ (err).code === 'EADDRINUSE') {
-      stderr.write(`[error] usage port ${resolvedPort} is in use (another rcf view process, or a different service).\n`);
+      stderr.write(`[error] usage port ${resolvedPort} is in use (another rcf audit view process, or a different service).\n`);
       stderr.write('Pass --port <n> or set RCF_VIEW_PORT to pick a free port.\n');
       return 2;
     }
@@ -286,7 +288,7 @@ export async function main(argv, deps = {}) {
     return 1;
   }
 
-  stdout.write(`rcf view server listening at ${server.url}\n`);
+  stdout.write(`rcf audit view server listening at ${server.url}\n`);
   stdout.write('watching rcf/ - Ctrl-C to shut down\n');
 
   maybeAutoOpen({

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/core/store/writer.js

@@ -1286,7 +1286,7 @@ export async function deleteDocument({ projectRoot, tree, id, options = {}, walk
   if (rootKinds.has(kind)) {
     return rcfError({
       kind: 'usage',
-      message: `delete: root singleton ${id} cannot be deleted via rcf delete`,
+      message: `delete: root singleton ${id} cannot be deleted via rcf define delete`,
       documentId: id,
     });
   }

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