rcf-lite 0.7.1 → 0.9.0

package/src/blueprint/conflicts.js

@@ -0,0 +1,351 @@
+// Blueprint conflict detection at apply time.
+//
+// Two conflict classes:
+//
+//  - `globalAdrTopic`: two applied blueprints both contributing a
+//    scope:global ADR on the same topic. The Phase 1 design brief
+//    named this class explicitly. From 0.4.5 the detector consults
+//    `manifest.resolutions[]` and skips a would-be conflict when a
+//    resolution matches the topic + both {slug, adrId} pairs; the two
+//    blueprint ADRs then co-reside on disk as superseded history
+//    alongside the project-level ADR that supersedes them.
+//
+//  - `crossBlueprintOwnership`: an incoming contribution declares an
+//    id that another currently-applied blueprint already owns in its
+//    manifest record. The manifest's appliedBlueprintRecord.contributions[]
+//    list is the authoritative ownership record; two blueprints cannot
+//    both claim the same id. This is the ambiguity-class check that
+//    used to live inside `isNamespacedFor` grammar (blueprint `spa`
+//    silently claiming `ADR-005-spa-theme` because the string
+//    startsWith `spa-`). Grammar is no longer a trust surface here --
+//    the manifest is.
+//
+// Every other class the design brief names (non-global TACs/ADRs/REQs/USs
+// /FBSes, standards-value conflicts, manifest overlap) is either
+// namespaced away or deferred to Phase 3 iteration per the design
+// brief's prototype-unknown #1.
+//
+// Pure functions. Read the applied blueprints' contributions (as stored
+// in `manifest.blueprints[]`) plus the incoming blueprint's contribution
+// list, and return zero-or-more Conflict records. No I/O.
+
+import { matchingResolution } from './resolutions.js';
+
+/**
+ * @typedef {(
+ *   { kind: 'globalAdrTopic',
+ *     topic: string,
+ *     incoming: { slug: string, id: string, path: string, title?: string, decision?: string, source?: string },
+ *     existing: { slug: string, id: string, path: string, title?: string, decision?: string } }
+ *   |
+ *   { kind: 'crossBlueprintOwnership',
+ *     id: string,
+ *     incoming: { slug: string, path: string },
+ *     existing: { slug: string, path: string } }
+ * )} Conflict
+ *
+ * `incoming.source` on the globalAdrTopic shape is the CLI-supplied
+ * source label the operator typed on `rcf blueprint add SRC`; the
+ * renderer inlines it into option 3 (`rcf blueprint supersede <topic>
+ * --incoming <source>`) so the printed command is copy-paste-runnable
+ * verbatim from the refused-add state. Absent when the caller did not
+ * thread a source label (unit-test paths).
+ */
+
+/**
+ * scope:global ADR topic conflicts across two applied blueprints.
+ *
+ * Optional `manifest` argument: when supplied and the manifest carries a
+ * matching entry in `manifest.resolutions[]`, the conflict is honoured
+ * (dropped from the returned list). Callers that want the raw shape
+ * (`rcf blueprint diff <topic>` needs to inspect both ADRs even when a
+ * resolution exists) can pass `manifest: null` to bypass the honour step.
+ *
+ * @param {Array<{
+ *   slug: string,
+ *   contributions?: Array<{ id: string, kind: string, path: string, scope?: string, topic?: string }>
+ * }>} appliedBlueprints
+ * @param {{
+ *   slug: string,
+ *   contributions?: Array<{ id: string, kind: string, path: string, scope?: string, topic?: string }>
+ * }} incoming
+ * @param {object|null} [manifest] - optional manifest for resolutions[] lookup
+ * @returns {Conflict[]}
+ */
+export function detectGlobalAdrConflicts(appliedBlueprints, incoming, manifest = null) {
+  const conflicts = [];
+  const incomingGlobals = (incoming.contributions ?? [])
+    .filter((c) => c.kind === 'adr' && c.scope === 'global' && typeof c.topic === 'string');
+  if (incomingGlobals.length === 0) return conflicts;
+
+  for (const applied of appliedBlueprints ?? []) {
+    if (applied.slug === incoming.slug) continue; // re-apply of the same blueprint is not a conflict
+    for (const existing of applied.contributions ?? []) {
+      if (existing.kind !== 'adr' || existing.scope !== 'global' || typeof existing.topic !== 'string') continue;
+      for (const incomingAdr of incomingGlobals) {
+        if (existing.topic !== incomingAdr.topic) continue;
+        // Honour a matching resolution if the caller passed a manifest.
+        // The resolution list is small (one entry per resolved topic
+        // per project) so the linear scan inside matchingResolution is
+        // fine at this scale.
+        if (manifest !== null) {
+          const resolved = matchingResolution(manifest, {
+            topic: existing.topic,
+            incoming: { slug: incoming.slug, adrId: incomingAdr.id },
+            existing: { slug: applied.slug, adrId: existing.id },
+          });
+          if (resolved) continue;
+        }
+        conflicts.push({
+          kind: 'globalAdrTopic',
+          topic: existing.topic,
+          incoming: { slug: incoming.slug, id: incomingAdr.id, path: incomingAdr.path },
+          existing: { slug: applied.slug, id: existing.id, path: existing.path },
+        });
+      }
+    }
+  }
+  return conflicts;
+}
+
+/**
+ * Cross-blueprint ownership conflicts: an incoming contribution id is
+ * already recorded as owned by a DIFFERENT applied blueprint. This
+ * detector is what makes `spa` vs `spa-theme` cross-claim impossible
+ * once one of the two has applied -- the second-mover's incoming id
+ * hits the first-mover's manifest record and is refused, regardless
+ * of how the id string parses.
+ *
+ * Re-apply of the same slug (`applied.slug === incoming.slug`) is
+ * skipped: same blueprint owning its own ids across re-apply is the
+ * intended idempotent case.
+ *
+ * @param {Array<{
+ *   slug: string,
+ *   contributions?: Array<{ id: string, kind: string, path: string }>
+ * }>} appliedBlueprints
+ * @param {{
+ *   slug: string,
+ *   contributions?: Array<{ id: string, kind: string, path: string }>
+ * }} incoming
+ * @returns {Conflict[]}
+ */
+export function detectCrossBlueprintClaims(appliedBlueprints, incoming) {
+  const conflicts = [];
+  const incomingList = incoming.contributions ?? [];
+  if (incomingList.length === 0) return conflicts;
+
+  // Index applied contributions by id -> { slug, path } for a single-
+  // pass scan. Skip the incoming blueprint's own previously-recorded
+  // entries (that is the re-apply path, not a claim).
+  const owned = new Map(); // id -> { slug, path }
+  for (const applied of appliedBlueprints ?? []) {
+    if (applied.slug === incoming.slug) continue;
+    for (const c of applied.contributions ?? []) {
+      if (!owned.has(c.id)) owned.set(c.id, { slug: applied.slug, path: c.path });
+    }
+  }
+  if (owned.size === 0) return conflicts;
+
+  for (const incomingC of incomingList) {
+    const priorOwner = owned.get(incomingC.id);
+    if (!priorOwner) continue;
+    conflicts.push({
+      kind: 'crossBlueprintOwnership',
+      id: incomingC.id,
+      incoming: { slug: incoming.slug, path: incomingC.path },
+      existing: { slug: priorOwner.slug, path: priorOwner.path },
+    });
+  }
+  return conflicts;
+}
+
+/**
+ * Render a conflict report for operator eyes. Reshaped in 0.4.5:
+ *
+ *   - Per-conflict block LEADS with the ADR titles and a one-sentence
+ *     decision each (topic string in parens), ids and paths as a
+ *     footer. If titles / decisions are not available (the detector
+ *     was not given tree access), the block falls back to the id +
+ *     path pair as the header.
+ *   - Resolution list carries only implemented options with actual
+ *     blueprint slugs filled in (no more placeholder `<slug>` prose).
+ *     A follow-up superset-add reintroduces the conflict; the operator
+ *     is not offered rename ceremonies for that.
+ *
+ * The old three-line resolutions blurb ("run `rcf blueprint remove
+ * <slug>` on the incoming side's slug if it is already partially in-
+ * flight, then leave things as they are") is gone -- neither `<slug>`
+ * placeholder was actually implementable end-to-end, and the operator
+ * has been reading past it since Phase 1.
+ *
+ * @param {Conflict[]} conflicts
+ * @returns {string}
+ */
+export function renderConflictReport(conflicts) {
+  if (conflicts.length === 0) return '';
+  const lines = [];
+  lines.push(`[rcf] blueprint add refused: ${conflicts.length} conflict(s) detected.`);
+  lines.push('');
+  for (let i = 0; i < conflicts.length; i += 1) {
+    const c = conflicts[i];
+    if (i > 0) lines.push('');
+    if (c.kind === 'globalAdrTopic') {
+      // Header: title + decision when available, id + path otherwise.
+      const incomingHeader = renderAdrHeader(c.incoming);
+      const existingHeader = renderAdrHeader(c.existing);
+      lines.push(`conflict on topic (${c.topic}):`);
+      lines.push(`  incoming  blueprint ${c.incoming.slug}: ${incomingHeader}`);
+      lines.push(`  existing  blueprint ${c.existing.slug}: ${existingHeader}`);
+      lines.push(`  refs:     ${c.incoming.id} at ${c.incoming.path}`);
+      lines.push(`            ${c.existing.id} at ${c.existing.path}`);
+      lines.push('');
+      // Round-3 (Baz ruling): option 3 must be executable VERBATIM
+      // from this refused-add state. supersede accepts `--incoming
+      // <source>` and carries the SAME source path the operator just
+      // typed on `rcf blueprint add SRC`, so the printed command is
+      // copy-paste-runnable. Fall back to `<source>` only when the
+      // caller did not thread the source label onto the conflict
+      // (unit-test paths that call renderConflictReport directly).
+      const sourceLabel = typeof c.incoming.source === 'string' && c.incoming.source.length > 0
+        ? c.incoming.source
+        : '<source>';
+      lines.push('  resolutions (pick one, honest options only):');
+      lines.push(`    1. Adopt the incoming blueprint. Run:`);
+      lines.push(`         rcf blueprint remove ${c.existing.slug}`);
+      lines.push(`       then re-run \`rcf blueprint add ${sourceLabel}\`.`);
+      lines.push(`    2. Keep the existing blueprint. Do not add ${c.incoming.slug} on this project.`);
+      lines.push(`    3. Author a project-level ADR that supersedes both. Run:`);
+      lines.push(`         rcf blueprint supersede ${c.topic} --incoming ${sourceLabel}`);
+      lines.push(`       which scaffolds the project ADR (both blueprint ADRs listed as superseded)`);
+      lines.push(`       and registers the resolution in the manifest, then re-run \`rcf blueprint add ${sourceLabel}\`.`);
+      lines.push(`    4. Declare the resolution on the add itself:`);
+      lines.push(`         rcf blueprint add ${sourceLabel} --resolve ${c.topic}=project:<ADR-id>`);
+      lines.push(`       which records the resolution and skips the remove/re-add ceremony.`);
+    } else if (c.kind === 'crossBlueprintOwnership') {
+      lines.push(`conflict on id ${c.id}:`);
+      lines.push(`  incoming  blueprint ${c.incoming.slug} declares ${c.id} at ${c.incoming.path}`);
+      lines.push(`  existing  blueprint ${c.existing.slug} already owns ${c.id} at ${c.existing.path}`);
+      lines.push('');
+      lines.push('  resolutions (pick one, honest options only):');
+      lines.push(`    1. Adopt the incoming blueprint. Run:`);
+      lines.push(`         rcf blueprint remove ${c.existing.slug}`);
+      lines.push(`       then re-run the incoming add.`);
+      lines.push(`    2. Keep the existing blueprint. Do not add ${c.incoming.slug} on this project.`);
+      lines.push(`    3. Fix the incoming blueprint's contribution ids (author-side change);`);
+      lines.push(`       cross-blueprint id claims cannot be resolved by a manifest ruling.`);
+    }
+  }
+  lines.push('');
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Render a conflict report as a JSON object for agent-driven
+ * composition. Shape:
+ *
+ * ```
+ * {
+ *   "refused": true,
+ *   "conflictCount": N,
+ *   "conflicts": [
+ *     { kind: 'globalAdrTopic', topic, incoming: {slug,id,path,title?,decision?}, existing: {...}, resolutions: [...] },
+ *     { kind: 'crossBlueprintOwnership', id, incoming, existing, resolutions: [...] }
+ *   ]
+ * }
+ * ```
+ *
+ * The resolutions list on each conflict is the machine-readable
+ * counterpart to the prose in renderConflictReport: `{ id, description,
+ * commands }` triples, no placeholders.
+ *
+ * @param {Conflict[]} conflicts
+ * @returns {object}
+ */
+export function conflictReportJson(conflicts) {
+  return {
+    refused: conflicts.length > 0,
+    conflictCount: conflicts.length,
+    conflicts: conflicts.map((c) => {
+      if (c.kind === 'globalAdrTopic') {
+        const sourceLabel = typeof c.incoming.source === 'string' && c.incoming.source.length > 0
+          ? c.incoming.source
+          : '<source>';
+        return {
+          kind: c.kind,
+          topic: c.topic,
+          incoming: pruneAdrRef(c.incoming),
+          existing: pruneAdrRef(c.existing),
+          resolutions: [
+            {
+              id: 'adoptIncoming',
+              description: `Adopt the incoming blueprint (${c.incoming.slug}); remove the existing (${c.existing.slug}).`,
+              commands: [`rcf blueprint remove ${c.existing.slug}`, `rcf blueprint add ${sourceLabel}`],
+            },
+            {
+              id: 'keepExisting',
+              description: `Keep the existing blueprint (${c.existing.slug}); do not add ${c.incoming.slug}.`,
+              commands: [],
+            },
+            {
+              id: 'supersede',
+              description: `Author a project-level ADR that supersedes both blueprint ADRs on topic '${c.topic}'.`,
+              commands: [`rcf blueprint supersede ${c.topic} --incoming ${sourceLabel}`, `rcf blueprint add ${sourceLabel}`],
+            },
+            {
+              id: 'declareOnAdd',
+              description: `Declare the resolution on the incoming add itself.`,
+              commands: [`rcf blueprint add ${sourceLabel} --resolve ${c.topic}=project:<ADR-id>`],
+            },
+          ],
+        };
+      }
+      // crossBlueprintOwnership
+      return {
+        kind: c.kind,
+        id: c.id,
+        incoming: c.incoming,
+        existing: c.existing,
+        resolutions: [
+          {
+            id: 'adoptIncoming',
+            description: `Adopt the incoming blueprint (${c.incoming.slug}); remove the existing (${c.existing.slug}).`,
+            commands: [`rcf blueprint remove ${c.existing.slug}`],
+          },
+          {
+            id: 'keepExisting',
+            description: `Keep the existing blueprint (${c.existing.slug}); do not add ${c.incoming.slug}.`,
+            commands: [],
+          },
+          {
+            id: 'fixIncomingIds',
+            description: `Fix the incoming blueprint's contribution ids at authoring; cross-blueprint id claims cannot be resolved by a manifest ruling.`,
+            commands: [],
+          },
+        ],
+      };
+    }),
+  };
+}
+
+function renderAdrHeader(side) {
+  if (typeof side.title === 'string' && side.title.length > 0) {
+    if (typeof side.decision === 'string' && side.decision.length > 0) {
+      return `${side.title} — ${side.decision}`;
+    }
+    return side.title;
+  }
+  return `${side.id} at ${side.path}`;
+}
+
+function pruneAdrRef(side) {
+  const out = { slug: side.slug, id: side.id, path: side.path };
+  if (typeof side.title === 'string' && side.title.length > 0) out.title = side.title;
+  if (typeof side.decision === 'string' && side.decision.length > 0) out.decision = side.decision;
+  // Round-3: the incoming side may also carry `source` (the CLI arg
+  // to `rcf blueprint add SRC`); surface it on --json so agent-driven
+  // composition has the same copy-paste-runnable command the terminal
+  // renderer produces.
+  if (typeof side.source === 'string' && side.source.length > 0) out.source = side.source;
+  return out;
+}

package/src/blueprint/diff.js

@@ -0,0 +1,82 @@
+// `rcf blueprint diff <topic>` implementation.
+//
+// Side-by-side view of every applied blueprint's scope:global ADR on a
+// given topic. Reads titles + decisions off the tree's byId map (the
+// walker already parsed and validated the ADR bodies) and returns
+// them in a shape a CLI renderer can format into two columns.
+//
+// This verb is read-only. It does not run the conflict detector -- an
+// operator staring at a diff is usually deciding how to resolve the
+// conflict, not asking whether one exists.
+
+/**
+ * @typedef {object} DiffAdrEntry
+ * @property {string} slug        blueprint slug
+ * @property {string} adrId       ADR id inside that blueprint's contribution set
+ * @property {string} path        rcf-relative path to the ADR file
+ * @property {string} [title]     ADR title (when the tree carries the loaded doc)
+ * @property {string} [decision]  ADR decision (ditto)
+ * @property {string} [context]   ADR context (ditto)
+ * @property {string} [status]    ADR status (ditto)
+ */
+
+/**
+ * @typedef {object} DiffResult
+ * @property {string}          topic
+ * @property {DiffAdrEntry[]}  entries    two or more when a conflict exists
+ */
+
+/**
+ * @param {object} args
+ * @param {import('#core/store/walker.js').TreeModel} args.tree
+ * @param {string} args.topic
+ * @returns {DiffResult}
+ */
+export function diffBlueprintTopic({ tree, topic }) {
+  const entries = [];
+  const applied = Array.isArray(tree.manifest?.blueprints) ? tree.manifest.blueprints : [];
+  for (const bp of applied) {
+    for (const c of bp.contributions ?? []) {
+      if (c.kind !== 'adr' || c.scope !== 'global' || c.topic !== topic) continue;
+      const entry = { slug: bp.slug, adrId: c.id, path: c.path };
+      const doc = tree.byId?.get(c.id);
+      if (doc && typeof doc === 'object') {
+        if (typeof doc.title === 'string') entry.title = doc.title;
+        if (typeof doc.decision === 'string') entry.decision = doc.decision;
+        if (typeof doc.context === 'string') entry.context = doc.context;
+        if (typeof doc.status === 'string') entry.status = doc.status;
+      }
+      entries.push(entry);
+    }
+  }
+  return { topic, entries };
+}
+
+/**
+ * Render a DiffResult as an operator-readable two-column-ish block.
+ * The renderer intentionally stays plain-text and terminal-friendly
+ * (no ANSI, no fancy box-drawing) so it composes with piped output.
+ *
+ * @param {DiffResult} diff
+ * @returns {string}
+ */
+export function renderDiff(diff) {
+  const lines = [];
+  lines.push(`[rcf] blueprint diff on topic (${diff.topic}): ${diff.entries.length} scope:global ADR(s).`);
+  if (diff.entries.length === 0) {
+    lines.push('');
+    lines.push(`  no applied blueprint carries a scope:global ADR on '${diff.topic}'.`);
+    return `${lines.join('\n')}\n`;
+  }
+  for (let i = 0; i < diff.entries.length; i += 1) {
+    const e = diff.entries[i];
+    lines.push('');
+    lines.push(`  [${i + 1}] blueprint ${e.slug}`);
+    lines.push(`      id:       ${e.adrId}`);
+    lines.push(`      path:     ${e.path}`);
+    if (e.title)    lines.push(`      title:    ${e.title}`);
+    if (e.status)   lines.push(`      status:   ${e.status}`);
+    if (e.decision) lines.push(`      decision: ${e.decision}`);
+  }
+  return `${lines.join('\n')}\n`;
+}

package/src/blueprint/index.js

@@ -0,0 +1,12 @@
+// Public surface for the blueprint mechanism.
+
+export { applyBlueprint } from './apply.js';
+export { listBlueprints } from './list.js';
+export { removeBlueprint } from './remove.js';
+export { loadBlueprint } from './loader.js';
+export { detectGlobalAdrConflicts, detectCrossBlueprintClaims, renderConflictReport, conflictReportJson } from './conflicts.js';
+export { stampId, parseIdParts, namespaceStyleFor, isNamespacedFor } from './namespace.js';
+export { registerStandardsPack, listStandards } from './standards.js';
+export { nextResolutionId, matchingResolution } from './resolutions.js';
+export { supersedeBlueprintTopic } from './supersede.js';
+export { diffBlueprintTopic, renderDiff } from './diff.js';

package/src/blueprint/list.js

@@ -0,0 +1,21 @@
+// Blueprint list. Reads manifest.blueprints[] and returns rows in
+// appliedAt order. Rows are already validated by the schema; this
+// module is a projection.
+
+/**
+ * @param {import('#core/store/walker.js').TreeModel} tree
+ * @returns {Array<{ slug: string, version: string, appliedAt: string, source: string, namespace: string | null, contributionCount: number }>}
+ */
+export function listBlueprints(tree) {
+  const list = tree.manifest?.blueprints ?? [];
+  return [...list]
+    .sort((a, b) => String(a.appliedAt).localeCompare(String(b.appliedAt)))
+    .map((b) => ({
+      slug: b.slug,
+      version: b.version,
+      appliedAt: b.appliedAt,
+      source: b.source,
+      namespace: b.namespace ?? null,
+      contributionCount: Array.isArray(b.contributions) ? b.contributions.length : 0,
+    }));
+}

package/src/blueprint/loader.js

@@ -0,0 +1,163 @@
+// Blueprint loader. Phase 1 keeps the loader local: a blueprint source
+// is a filesystem directory containing a `blueprint.json` metadata file
+// plus a `contributions/` subdirectory. The metadata declares the
+// blueprint's slug, version, and every contribution's { id, kind, path
+// (relative to contributions/) }. ADR contributions may carry a
+// `scope: 'global'` tag plus a `topic` string; these are the only
+// contributions the conflict detector reasons about.
+//
+// The registry / git-ref resolver is a Phase 2 concern (SPA and REST
+// blueprints ship as npm packages); this loader intentionally has no
+// network path so tests are hermetic.
+
+import { readFile, stat } from 'node:fs/promises';
+import { isAbsolute, join, resolve } from 'node:path';
+
+import { rcfError } from '../core/errors/index.js';
+
+// Contribution kinds a blueprint MAY carry. The RCF hierarchy is composed
+// downward: a blueprint contributes REQuirements, UserStories, TACs and
+// ADRs (plus their supporting FBS / TS / CN artefacts written by later
+// phases). PRDs, TADs and the Build Sequence are project-level singletons
+// -- one PRD per project, one TAD per project, one BS per project -- so
+// no blueprint gets to own them. FBS is excluded by ratified principle
+// (composition happens at the requirements layer, not the build layer).
+const CONTRIBUTABLE_KINDS = new Set(['req', 'us', 'tac', 'adr', 'ts', 'cn']);
+const ROOT_SINGLETON_KINDS = new Set(['prd', 'tad', 'bs']);
+const EXCLUDED_KINDS = new Set(['fbs']);
+
+/**
+ * @typedef {object} BlueprintContribution
+ * @property {string} id           canonical id (bare or already namespaced)
+ * @property {'prd'|'req'|'us'|'tad'|'tac'|'adr'|'bs'|'fbs'|'ts'|'cn'} kind
+ * @property {string} path         relative to the blueprint's contributions/
+ * @property {'global'} [scope]    ADR only; marks whole-project decisions
+ * @property {string}   [topic]    ADR only when scope=global; conflict key
+ */
+
+/**
+ * @typedef {object} LoadedBlueprint
+ * @property {string} slug
+ * @property {string} version
+ * @property {string} source        source directory (absolute)
+ * @property {BlueprintContribution[]} contributions
+ */
+
+/**
+ * Load a blueprint's metadata from a directory containing blueprint.json.
+ *
+ * @param {string} source - path to the blueprint's root directory
+ * @returns {Promise<LoadedBlueprint | import('../core/errors/index.js').RcfError>}
+ */
+export async function loadBlueprint(source) {
+  const root = resolve(source);
+  const metaPath = join(root, 'blueprint.json');
+  try {
+    await stat(metaPath);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return rcfError({
+        kind: 'usage',
+        message: `blueprint: no blueprint.json found at ${metaPath}`,
+        filePath: metaPath,
+      });
+    }
+    return rcfError({ kind: 'ioFailure', message: `blueprint: ${err.message}`, filePath: metaPath });
+  }
+  let raw;
+  try {
+    raw = await readFile(metaPath, 'utf8');
+  } catch (err) {
+    return rcfError({ kind: 'ioFailure', message: `blueprint: read failed: ${err.message}`, filePath: metaPath });
+  }
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch (err) {
+    return rcfError({ kind: 'parseFailure', message: `blueprint: JSON parse failed: ${err.message}`, filePath: metaPath });
+  }
+  const validation = validateMetadata(doc, metaPath);
+  if (validation) return validation;
+  return {
+    slug: doc.slug,
+    version: doc.version,
+    source: root,
+    contributions: Array.isArray(doc.contributions) ? doc.contributions : [],
+  };
+}
+
+function validateMetadata(doc, metaPath) {
+  if (typeof doc !== 'object' || doc === null) {
+    return rcfError({ kind: 'validation', message: 'blueprint.json must be a JSON object', filePath: metaPath });
+  }
+  if (typeof doc.slug !== 'string' || !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(doc.slug)) {
+    return rcfError({ kind: 'validation', message: `blueprint.json: slug '${doc.slug}' is not a valid kebab slug`, filePath: metaPath });
+  }
+  if (typeof doc.version !== 'string' || !/^\d+\.\d+\.\d+$/.test(doc.version)) {
+    return rcfError({ kind: 'validation', message: `blueprint.json: version '${doc.version}' is not semver`, filePath: metaPath });
+  }
+  if (doc.contributions !== undefined && !Array.isArray(doc.contributions)) {
+    return rcfError({ kind: 'validation', message: 'blueprint.json: contributions must be an array', filePath: metaPath });
+  }
+  for (const c of doc.contributions ?? []) {
+    if (typeof c.id !== 'string' || typeof c.kind !== 'string' || typeof c.path !== 'string') {
+      return rcfError({ kind: 'validation', message: 'blueprint.json: every contribution needs { id, kind, path }', filePath: metaPath });
+    }
+    // Kind gate. Blueprints compose downward from project singletons;
+    // PRD / TAD / BS are per-project artefacts a blueprint never gets
+    // to overwrite, and FBS is excluded by ratified principle
+    // (composition sits at the requirements layer). This is enforced
+    // pre-registry so a mis-authored blueprint fails at load time
+    // rather than at the apply-time collision.
+    if (ROOT_SINGLETON_KINDS.has(c.kind)) {
+      return rcfError({
+        kind: 'validation',
+        message: `blueprint.json: contribution ${c.id} kind '${c.kind}' is a project singleton and cannot be blueprint-owned`,
+        filePath: metaPath,
+      });
+    }
+    if (EXCLUDED_KINDS.has(c.kind)) {
+      return rcfError({
+        kind: 'validation',
+        message: `blueprint.json: contribution ${c.id} kind '${c.kind}' is excluded from blueprint composition by ratified principle (FBS lives at the project's build layer)`,
+        filePath: metaPath,
+      });
+    }
+    if (!CONTRIBUTABLE_KINDS.has(c.kind)) {
+      return rcfError({
+        kind: 'validation',
+        message: `blueprint.json: contribution ${c.id} kind '${c.kind}' is not a recognised contributable kind (expected one of: ${[...CONTRIBUTABLE_KINDS].join(', ')})`,
+        filePath: metaPath,
+      });
+    }
+    // Path guard. Contribution paths are ALWAYS relative to the
+    // blueprint's contributions/ directory. Reject absolute paths and
+    // `..` traversal outright; a registry-fetched blueprint that
+    // slipped through with an escaping path would land arbitrary
+    // bytes wherever the resolved path pointed. Belt-and-braces
+    // before Phase 2 fronts this loader with a registry.
+    const pathError = validateContributionPath(c.path, c.id);
+    if (pathError) return rcfError({ kind: 'validation', message: pathError, filePath: metaPath });
+    if (c.scope !== undefined && c.scope !== 'global') {
+      return rcfError({ kind: 'validation', message: `blueprint.json: contribution ${c.id} scope must be 'global' when present`, filePath: metaPath });
+    }
+    if (c.scope === 'global' && typeof c.topic !== 'string') {
+      return rcfError({ kind: 'validation', message: `blueprint.json: scope=global contribution ${c.id} requires a topic`, filePath: metaPath });
+    }
+  }
+  return null;
+}
+
+function validateContributionPath(p, id) {
+  if (typeof p !== 'string' || p.length === 0) {
+    return `blueprint.json: contribution ${id} path must be a non-empty string`;
+  }
+  if (isAbsolute(p) || /^[A-Za-z]:[\\/]/.test(p)) {
+    return `blueprint.json: contribution ${id} path '${p}' must be relative (absolute paths are refused)`;
+  }
+  const segments = p.split(/[\\/]/);
+  if (segments.some((s) => s === '..')) {
+    return `blueprint.json: contribution ${id} path '${p}' contains a '..' segment (parent-directory traversal is refused)`;
+  }
+  return null;
+}

package/src/blueprint/manifest-writer.js

@@ -0,0 +1,49 @@
+// Shared atomic writer for the manifest.blueprints[] and
+// manifest.standards[] sections. Modelled on
+// src/ui-baseline/manifest-writer.js (schema-validate the composed
+// manifest, tmp-write + rename).
+
+import { mkdir, rename, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { rcfError } from '../core/errors/index.js';
+import { validateDocument } from '#core/store';
+
+/**
+ * Read the manifest from tree, apply `mutate(manifest)`, revalidate,
+ * atomically write. Returns the updated manifest or an RcfError.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {object} args.manifest - the current manifest object
+ * @param {(next: object) => void} args.mutate - mutates `next` in place
+ * @param {boolean} [args.dryRun]
+ * @returns {Promise<{ manifest: object } | import('../core/errors/index.js').RcfError>}
+ */
+export async function updateManifest({ projectRoot, manifest, mutate, dryRun = false }) {
+  const next = deepClone(manifest ?? {});
+  mutate(next);
+  const relPath = 'rcf/manifest.json';
+  const validation = validateDocument({ doc: next, kind: 'manifest', filePath: relPath });
+  if (validation) return validation;
+  if (dryRun) return { manifest: next };
+  const absPath = join(projectRoot, 'rcf', 'manifest.json');
+  try {
+    await mkdir(dirname(absPath), { recursive: true });
+    const tmp = `${absPath}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+    try {
+      await rename(tmp, absPath);
+    } catch (err) {
+      try { await unlink(tmp); } catch { /* ignore */ }
+      throw err;
+    }
+  } catch (err) {
+    return rcfError({ kind: 'ioFailure', message: `manifest write failed: ${err.message}`, filePath: relPath });
+  }
+  return { manifest: next };
+}
+
+function deepClone(x) {
+  return JSON.parse(JSON.stringify(x));
+}