rcf-lite 0.0.1 → 0.8.0

package/src/cli/coverage.js

@@ -0,0 +1,219 @@
+// `rcf coverage` subcommand handler. Reports structural coverage over
+// the REQ chain (PRD -> REQ -> US -> AC -> TS -> TC). Phase 5 §D2 / §D10.
+//
+// Shallow-any default (any AC covered by any TC = REQ covered);
+// --strict opts into per-AC-strict. --strict on a tree with uncovered
+// ACs exits 4 (CI-gate friendly). Otherwise coverage always exits 0 -
+// the gap count is data, not a refusal.
+//
+// Phase-boundary reminder (§D2, §1.4): this verb is a MECHANICAL /
+// DETERMINISTIC structural check. It does NOT answer "does the AC
+// set adequately capture the REQ's intent?" - that non-deterministic
+// question belongs to a later prompting + MCP resources phase (7+).
+
+import { parseArgs } from 'node:util';
+
+import { formatErrors } from '#core/errors';
+import { resolveTestPointers, walkTree } from '#core/store';
+import { findProjectRoot } from '../view/index.js';
+import {
+  classifyCoverageScope,
+  computeCoverage,
+  formatJson,
+  formatMermaid,
+  formatTable,
+} from '../query/index.js';
+import {
+  findAttestationDrift,
+  findAttestationMissing,
+  findProvenanceMissing,
+  findServicesWithEmptyAffectedFbsIds,
+} from '../query/attestation.js';
+
+const OPTION_SPEC = {
+  strict: { type: 'boolean' },
+  format: { type: 'string' },
+  help: { type: 'boolean' },
+  // Phase 10 (X2 CodeNode bridge, D11): layer the code axis onto coverage.
+  'with-code': { type: 'boolean' },
+  // 0.7.0 verification-integrity: opt-in extra gate on --strict that
+  // refuses any TS still `draft` after Stage 4 (spec §7.2).
+  'require-approved': { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf coverage [scope-id] [options]
+
+Report structural coverage over the REQ chain (PRD -> REQ -> US -> AC
+-> TS -> TC). A TC counts as covering its AC only when its testPointer
+(filePath::testName) resolves to a real test in the working tree; a TC
+whose pointer does not resolve is reported as covered-unresolved, never
+counted as coverage. Default is shallow-any (any AC covered by any
+resolving TC = REQ covered); --strict flips to per-AC-strict (every AC
+has resolving TC coverage).
+
+This is a mechanical / deterministic structural check. It does NOT
+answer 'does the AC set adequately capture the REQ's intent?' - that
+non-deterministic question is out of scope for Phase 5 (belongs to a
+later prompting + MCP resources phase).
+
+Positional:
+  scope-id                  Optional PRD / REQ / US id to scope
+                            coverage to a subtree. Below-AC ids
+                            (AC / TS / TC / FBS / TAC / ADR / BS /
+                            TAD) are refused with exit 2.
+
+Options:
+  --strict                  Per-AC-strict mode; exits 4 on any gap. Also
+                            runs the attestation × profile matrix over
+                            every AC that binds a dependsOnServices
+                            entry (verification-integrity 0.7.0 §5.2):
+                            attestation drift, missing provenance, and
+                            missing FBS-level attestation all exit 4.
+  --require-approved        Extra --strict gate: refuse any TS still at
+                            authoringStatus 'draft' after Stage 4
+                            (verification-integrity 0.7.0 §7.2). Off
+                            by default; opt-in via CI.
+  --with-code               Layer the code axis onto every AC: one of
+                            implemented-and-covered / implemented-uncovered
+                            / unimplemented, plus a tree-wide list of
+                            CN-orphaned code nodes. INFORMATIONAL ONLY -
+                            never blocks or affects the exit code (D11;
+                            the mark-complete gate is where CN
+                            completeness is enforced).
+  --format <format>         table (default) | json | mermaid
+  --help                    Print this help
+`;
+
+const VALID_FORMATS = new Set(['table', 'json', 'mermaid']);
+
+/**
+ * @param {string[]} argv - argv slice after `coverage`
+ * @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] usage ${err.message}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  const flags = parsed.values;
+  const positionals = parsed.positionals;
+  if (flags.help) { stdout.write(HELP); return 0; }
+
+  const format = flags.format ?? 'table';
+  if (!VALID_FORMATS.has(format)) {
+    stderr.write(`[error] usage coverage: unknown --format ${format} (expected table | json | mermaid)\n`);
+    return 2;
+  }
+  if (positionals.length > 1) {
+    stderr.write('[error] usage coverage: multiple positional ids are not supported\n');
+    return 2;
+  }
+
+  const projectRoot = await findProjectRoot(cwd);
+  if (!projectRoot) {
+    stderr.write('[error] usage no project root found (no rcf/manifest.json in this directory or any ancestor). Run `npx rcf init` to create and wire a project.\n');
+    return 2;
+  }
+  const { tree, errors } = await walkTree({ projectRoot });
+  if (errors.length > 0) {
+    stderr.write(`${formatErrors(errors, { verbose: false, strict: false })}\n`);
+    return 3;
+  }
+
+  let scopeId = null;
+  if (positionals.length === 1) {
+    scopeId = positionals[0];
+    // Reject wildcards / globs (spec §D13).
+    if (scopeId.includes('*') || scopeId.includes('?')) {
+      stderr.write('[error] usage coverage: wildcard / glob positional not supported\n');
+      return 2;
+    }
+    const classification = classifyCoverageScope(tree, scopeId);
+    if (classification === 'below-ac') {
+      stderr.write(
+        `[error] usage coverage: scope-id ${scopeId} is below the AC layer or off the REQ chain; ` +
+          'coverage scope must be a PRD / REQ / US id\n',
+      );
+      return 2;
+    }
+    if (classification === 'not-found' || classification === 'unknown-kind') {
+      stderr.write(`[error] usage coverage: id ${scopeId} not found\n`);
+      return 2;
+    }
+  }
+
+  // w-2026-07-28-005: resolve every TC's testPointer against the working
+  // tree first - "covered" means a pointer that resolves to a real test,
+  // and a TC that fails resolution surfaces as covered-unresolved.
+  const testPointers = await resolveTestPointers({ projectRoot, tree });
+  const result = computeCoverage(tree, {
+    strict: Boolean(flags.strict), scopeId, withCode: Boolean(flags['with-code']), testPointers,
+  });
+
+  let output;
+  if (format === 'json') output = formatJson(result, 'coverage');
+  else if (format === 'mermaid') output = formatMermaid(result, 'coverage');
+  else output = formatTable(result, 'coverage');
+  stdout.write(output);
+
+  // --strict on any gap = exit 4 (CI-gate friendly). Otherwise 0.
+  if (flags.strict && !result.ok) return 4;
+
+  // 0.7.0 verification-integrity extension: --strict also runs the
+  // attestation × profile matrix (spec §5.2). Three refusal classes:
+  // (1) attestation missing, (2) provenance missing, (3) attestation
+  // drift. All are additive — they never turn a passing coverage into
+  // a passing --strict run; they only add exit-4 refusals on new
+  // failure modes that the matrix now polices.
+  if (flags.strict) {
+    // Review N-3 (non-blocking): surface preFlightConfig services with
+    // empty affectedFbsIds so the operator knows findAttestationMissing
+    // is skipping them on purpose (honest-but-invisible without this
+    // line). Warn-only, additive, never turns a passing strict run
+    // into a failing one.
+    const emptyAffected = findServicesWithEmptyAffectedFbsIds(tree);
+    for (const s of emptyAffected) {
+      stderr.write(`[warn] coverage --strict: preFlightConfig service '${s.serviceId}' (${s.preFlightConfigId}) has empty affectedFbsIds; the attestation-missing detector cannot cross-check it until the back-reference is populated.\n`);
+    }
+
+    const missing = findAttestationMissing(tree);
+    const provMissing = findProvenanceMissing(tree);
+    const drift = findAttestationDrift(tree);
+    const refusals = [];
+    if (missing.length > 0) {
+      refusals.push('Attestation missing (FBSes listed in preflight affectedFbsIds but with no dependsOnServices entry):');
+      for (const m of missing) refusals.push(`  - ${m.fbsId}: run \`rcf fbs ${m.fbsId} depends-on --service ${m.serviceId} --mode ${m.attestationMode} --acs <acIds>\``);
+    }
+    if (provMissing.length > 0) {
+      refusals.push('Runtime provenance missing (TC covers an AC that binds a service):');
+      for (const p of provMissing) refusals.push(`  - ${p.tsId}/${p.tcId} on ${p.acId}: run \`rcf test-suite ${p.tsId} provenance --tc ${p.tcId} --profile <mock|stub|fixture|live>\``);
+    }
+    const drifts = drift.filter((d) => d.verdict === 'refuse');
+    if (drifts.length > 0) {
+      refusals.push('Attestation drift (§3.5 matrix refusal):');
+      for (const d of drifts) refusals.push(`  - ${d.tsId}/${d.tcId} on ${d.acId} (service ${d.serviceId}): ${d.reason}`);
+    }
+    if (refusals.length > 0) {
+      stderr.write(`[error] coverage --strict: refused - the verification-integrity matrix caught the following:\n${refusals.join('\n')}\n`);
+      return 4;
+    }
+
+    if (flags['require-approved']) {
+      const draftTsIds = (tree.testSuites ?? []).filter((ts) => ts.status !== 'approved').map((ts) => ts.id);
+      if (draftTsIds.length > 0) {
+        stderr.write(`[error] coverage --strict --require-approved: refused - ${draftTsIds.length} test suite(s) still not approved: ${draftTsIds.join(', ')}\n`);
+        return 4;
+      }
+    }
+  }
+  return 0;
+}

package/src/cli/create.js

@@ -0,0 +1,358 @@
+// `rcf create <kind>` subcommand handler. Delegates to writer.js for
+// the actual persistence; this file handles CLI parsing + defaults +
+// pre-run tree walk. Phase 4 §D6 (revised).
+
+import { readFile } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+
+import { writeUnexpectedFailure } from '#core/errors';
+import { createDocument, deriveSlug, splitCnPath, walkTree } from '#core/store';
+import { deriveFileDeps, mapDerivedDepsToCnIds } from '#core/store/derive-deps.js';
+import { findProjectRoot } from '../view/index.js';
+// Track C+D §4.4: run the REQ-shape classifier on newly-created REQs
+// so downstream tooling (rcf req-baseline, rcf preflight, the Stage-1
+// gate) can act without a manual `rcf req-classify` first.
+import { classifyAndPersistReq } from '../req-detection/index.js';
+// Track C+D §5.3 moment 4: surface open baseline candidates on a
+// newly-created US so the operator sees the sweep queue immediately.
+import { openCandidatesForUs } from '../req-baseline/open-candidates.js';
+
+const OPTION_SPEC = {
+  parent: { type: 'string' },
+  id: { type: 'string' },
+  title: { type: 'string' },
+  description: { type: 'string' },
+  acs: { type: 'string' },
+  ac: { type: 'string' },
+  purpose: { type: 'string' },
+  'test-level': { type: 'string' },
+  slug: { type: 'string' },
+  'test-pointer': { type: 'string' },
+  'build-order': { type: 'string' },
+  'from-file': { type: 'string' },
+  'dry-run': { type: 'boolean' },
+  quiet: { type: 'boolean' },
+  help: { type: 'boolean' },
+  // Phase 10 (X2 CodeNode bridge): `rcf create cn` flags.
+  path: { type: 'string' },
+  deps: { type: 'string' },
+  'derive-deps': { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf create <kind> [options]
+
+Kinds: req | us | ac | tac | adr | fbs | ts | tc | cn
+
+Parent by kind (--parent takes the id of the DIRECT parent listed here,
+not any higher ancestor):
+  req  -> PRD id            us  -> REQ id             ac -> US id
+  tac  -> TAD id            adr -> TAD id             fbs -> BS id
+  ts   -> US id             tc  -> TS id
+  cn   -> no --parent; a Code Node's identity is its --path
+
+Note ts -> US id. A test suite hangs off the user story, not off the FBS
+that scheduled the work.
+
+Options:
+  --parent <id>             Required for every kind except cn (post-3.7
+                            every non-root child carries a mandatory
+                            parentId-style field). See the parent table
+                            above for which id each kind expects.
+  --id <id>                 Override auto-assigned id (refuses on
+                            collision)
+  --title <string>          Required for req / us / tac / adr / fbs / ts
+                            (ac / tc use --description)
+  --description <string>    Body description; required for ac / tc
+  --acs <id>[,<id>...]      Required for fbs and ts (one or more AC ids)
+  --ac <id>                 Required for tc (single AC id per test case)
+  --purpose <string>        Required for ts
+  --test-level <level>      Required for ts; one of
+                            unit / integration / e2e / contract / manual
+  --slug <slug>             Optional for tc; derived from description if
+                            absent
+  --test-pointer <path>     Required for tc; format filePath::testName.
+                            Coverage counts a TC only when this pointer
+                            resolves to a real test in the working tree
+  --build-order <int>       Optional for fbs; default = max+1 within its BS
+  --from-file <path>        Read body fields from a JSON file
+                            (merged with CLI fields; CLI wins on conflict)
+  --dry-run                 Print intended writes without executing
+  --quiet                   Suppress non-error stdout
+  --help                    Print this help
+
+Code Node (cn) options:
+  --path <path>             Repo-relative source path, optionally
+                            #symbol-suffixed (required)
+  --acs <ids>               Comma-separated AC ids this node implements
+                            (may be empty - an orphan CN is legitimate)
+  --deps <ids>              Comma-separated CN ids this node depends on
+  --derive-deps             Assist --deps with dependency-cruiser file-level
+                            analysis (dev-time only; never a runtime dep -
+                            errors helpfully when the tool is not resolvable)
+`;
+
+const VALID_KINDS = new Set(['req', 'us', 'ac', 'tac', 'adr', 'fbs', 'ts', 'tc', 'cn']);
+// Root-singleton kinds: created by `rcf init`, not by `rcf create`. When
+// a user reaches for `rcf create prd|tad|bs|manifest`, we return a clearer
+// message that points them at `rcf init` (BUG-010).
+const SINGLETON_KINDS = new Set(['prd', 'tad', 'bs', 'manifest']);
+
+/**
+ * @param {string[]} argv - argv slice after `create`
+ * @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] usage ${err.message}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  const flags = parsed.values;
+  const positionals = parsed.positionals;
+  if (flags.help) { stdout.write(HELP); return 0; }
+  // BUG-009 fix: split the two distinct usage errors so the operator can
+  // tell "kind missing" apart from "kind unknown". BUG-010 fix: singleton
+  // kinds (prd / tad / bs / manifest) get a clarifying "use rcf init"
+  // hint rather than the generic "unknown kind" line.
+  if (positionals.length === 0) {
+    stderr.write('[error] usage create: <kind> is required (one of req|us|ac|tac|adr|fbs|ts|tc)\n');
+    stderr.write(HELP);
+    return 2;
+  }
+  if (positionals.length > 1) {
+    stderr.write(`[error] usage create: expected exactly one <kind>, got ${positionals.length}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  const rawKind = positionals[0];
+  if (SINGLETON_KINDS.has(rawKind)) {
+    stderr.write(`[error] usage create: ${rawKind} is a root singleton — use \`rcf init\` to create it\n`);
+    return 2;
+  }
+  if (!VALID_KINDS.has(rawKind)) {
+    stderr.write(
+      `[error] usage create: unknown kind: ${rawKind} (expected one of req|us|ac|tac|adr|fbs|ts|tc)\n`,
+    );
+    stderr.write(HELP);
+    return 2;
+  }
+  const kind = rawKind;
+
+  const projectRoot = await findProjectRoot(cwd);
+  if (!projectRoot) {
+    stderr.write('[error] usage no project root found (no rcf/manifest.json in this directory or any ancestor). Run `npx rcf init` to create and wire a project.\n');
+    return 2;
+  }
+
+  const walkResult = await walkTree({ projectRoot });
+  // B5: pre-existing tree breakage no longer blocks write verbs - the
+  // write is gated on the POST-write tree state inside the writer, so
+  // repairing a broken tree is possible while net-new breakage is still
+  // refused.
+  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`);
+  }
+
+  let fileBody = null;
+  if (flags['from-file']) {
+    try {
+      const raw = await readFile(flags['from-file'], 'utf8');
+      fileBody = JSON.parse(raw);
+    } catch (err) {
+      stderr.write(`[error] usage create: cannot read --from-file: ${err.message}\n`);
+      return 2;
+    }
+  }
+
+  const body = { ...(fileBody ?? {}) };
+  // CLI wins on conflict.
+  if (flags.title !== undefined) body.title = flags.title;
+  if (flags.description !== undefined) body.description = flags.description;
+  if (flags.purpose !== undefined) body.purpose = flags.purpose;
+  if (flags['test-level'] !== undefined) body.testLevel = flags['test-level'];
+  // Phase 10: `cn`'s AC cross-link field is `implementsAcIds`, not `acIds`
+  // (fbs/ts share `acIds`) - --acs maps to whichever the kind expects.
+  if (flags.acs !== undefined) {
+    const ids = flags.acs.split(',').map((s) => s.trim()).filter(Boolean);
+    if (kind === 'cn') body.implementsAcIds = ids;
+    else body.acIds = ids;
+  }
+  if (kind === 'cn') {
+    if (flags.path !== undefined) body.path = flags.path;
+    if (flags.deps !== undefined) body.dependencies = flags.deps.split(',').map((s) => s.trim()).filter(Boolean);
+  }
+
+  const options = {
+    id: flags.id,
+    parentId: flags.parent,
+    dryRun: Boolean(flags['dry-run']),
+  };
+
+  // Per-kind mandatory-title / mandatory-description checks.
+  if (kind === 'ac' || kind === 'tc') {
+    if (!body.description) {
+      stderr.write(`[error] usage create ${kind}: --description is required\n`);
+      return 2;
+    }
+  } else if (kind === 'cn') {
+    if (!body.path) {
+      stderr.write('[error] usage create cn: --path is required\n');
+      return 2;
+    }
+    // Phase 10 D5: --derive-deps assist. Optional, dev-time only, never a
+    // runtime dependency - errors helpfully (exit 2) when the tool cannot
+    // be resolved rather than silently degrading or reaching for the
+    // network to install it.
+    if (flags['derive-deps']) {
+      const { file } = splitCnPath(body.path);
+      const derived = await deriveFileDeps({ projectRoot, filePath: file });
+      if (!derived.ok) {
+        stderr.write(`[error] usage create cn: --derive-deps: ${derived.message}\n`);
+        return 2;
+      }
+      const { cnIds, unmatched } = mapDerivedDepsToCnIds(walkResult.tree, derived.deps);
+      const existing = Array.isArray(body.dependencies) ? body.dependencies : [];
+      body.dependencies = [...new Set([...existing, ...cnIds])].sort();
+      if (unmatched.length > 0 && !flags.quiet) {
+        stdout.write(`[info] --derive-deps: ${unmatched.length} file-level import(s) have no matching CN yet, skipped: ${unmatched.join(', ')}\n`);
+      }
+    }
+  } else if (!body.title) {
+    stderr.write(`[error] usage create ${kind}: --title is required\n`);
+    return 2;
+  }
+
+  if (kind === 'ts') {
+    if (!body.purpose) { stderr.write('[error] usage create ts: --purpose is required\n'); return 2; }
+    if (!body.testLevel) { stderr.write('[error] usage create ts: --test-level is required\n'); return 2; }
+    if (!Array.isArray(body.acIds) || body.acIds.length === 0) {
+      stderr.write('[error] usage create ts: --acs is required (one or more AC ids)\n');
+      return 2;
+    }
+  }
+  if (kind === 'fbs') {
+    if (!Array.isArray(body.acIds) || body.acIds.length === 0) {
+      stderr.write('[error] usage create fbs: --acs is required (one or more AC ids)\n');
+      return 2;
+    }
+    if (flags['build-order'] !== undefined) {
+      const n = Number(flags['build-order']);
+      if (!Number.isInteger(n) || n < 1) {
+        stderr.write(`[error] usage create fbs: --build-order expects a positive integer, got ${flags['build-order']}\n`);
+        return 2;
+      }
+      options.buildOrder = n;
+    }
+  }
+  if (kind === 'tc') {
+    if (!flags.ac) { stderr.write('[error] usage create tc: --ac is required\n'); return 2; }
+    // w-2026-07-28-005: a TC without a pointer is a coverage claim with
+    // nothing behind it; refuse at the usage layer with the fix in hand.
+    if (!flags['test-pointer']) {
+      stderr.write('[error] usage create tc: --test-pointer is required (format filePath::testName; coverage counts a TC only when its pointer resolves to a real test)\n');
+      return 2;
+    }
+    body.acId = flags.ac;
+    // 0.8.0 slug-train (w-2026-07-28-012 landmine 4): deriveSlug returns ''
+    // on empty derivation; TC keeps its historical 'tc' fallback locally
+    // rather than letting deriveSlug bake it in.
+    options.slug = flags.slug ?? (deriveSlug(body.description) || 'tc');
+    options.testPointer = flags['test-pointer'];
+  }
+
+  const result = await createDocument({
+    projectRoot, tree: walkResult.tree, kind, body, options, walkErrors: walkResult.errors,
+  });
+  if (isRcfError(result)) {
+    return handleWriterError(result, stderr);
+  }
+  if (options.dryRun) {
+    if (!flags.quiet) stdout.write(`[dry-run] would create ${result.id} at ${result.filePath}\n`);
+    return 0;
+  }
+  if (!flags.quiet) {
+    stdout.write(`${result.id} created at ${result.filePath}\n`);
+  }
+  // Track C+D §5.3 moment 4: on a newly-created US under a
+  // shape-classified REQ, surface any baseline keys that will be OPEN
+  // until the operator resolves them. The Stage-1 gate refuses build
+  // on the same set; the operator sees the queue here rather than at
+  // the refusal.
+  if (kind === 'us') {
+    try {
+      const postWalk = await walkTree({ projectRoot });
+      const usDoc = postWalk.tree.byId.get(result.id);
+      if (usDoc) {
+        const open = openCandidatesForUs(postWalk.tree, usDoc);
+        if (open.length > 0 && !flags.quiet) {
+          const keys = open.map((c) => c.baselineKey).join(', ');
+          stdout.write(`${result.id} has ${open.length} open baseline candidate${open.length === 1 ? '' : 's'}: ${keys}\n`);
+          stdout.write(`  Resolve: rcf req-baseline sweep --req ${usDoc.reqId}\n`);
+        }
+      }
+    } catch (err) {
+      stderr.write(`[warn] baseline-scan (post-create-us): ${err.message}\n`);
+    }
+  }
+
+  // Track C+D §4.4: fire the classifier on newly-created REQs. Best-
+  // effort: a classification error surfaces on stderr but never fails
+  // the create (the REQ file was already written; classification is
+  // provenance layered on top).
+  if (kind === 'req') {
+    try {
+      const postWalk = await walkTree({ projectRoot });
+      const classifyOutcome = await classifyAndPersistReq({
+        projectRoot,
+        tree: postWalk.tree,
+        reqId: result.id,
+      });
+      if (classifyOutcome && classifyOutcome.ok === false) {
+        stderr.write(`[warn] ${classifyOutcome.message}\n`);
+      } else if (!flags.quiet && classifyOutcome?.block?.shapes?.length > 0) {
+        const shapes = classifyOutcome.block.shapes.join(', ');
+        stdout.write(`${result.id} shapeClassification: [${shapes}] (${classifyOutcome.block.reason})\n`);
+      }
+    } catch (err) {
+      stderr.write(`[warn] req-classify (post-create): ${err.message}\n`);
+    }
+  }
+  return 0;
+}
+
+const ERROR_KINDS = new Set([
+  'validation',
+  'missingFile',
+  'brokenReference',
+  'parseFailure',
+  'ioFailure',
+  'usage',
+]);
+
+function isRcfError(value) {
+  return Boolean(value) && typeof value === 'object' && typeof value.kind === 'string'
+    && ERROR_KINDS.has(value.kind) && typeof value.message === 'string';
+}
+
+function handleWriterError(err, stderr) {
+  const kind = err.kind;
+  // BUG-007 fix: spec §D15 mandates exit-1 emit
+  // `[rcf] unexpected failure: <msg>\n<stack>` — even under --quiet.
+  if (kind === 'ioFailure') {
+    writeUnexpectedFailure(err, stderr);
+    return 1;
+  }
+  stderr.write(`[error] ${kind} ${err.message}\n`);
+  if (kind === 'usage') return 2;
+  if (kind === 'validation' || kind === 'brokenReference') return 3;
+  if (kind === 'missingFile' || kind === 'parseFailure') return 2;
+  return 1;
+}