stack/packages/quality-rails/README.md

@mosaicstack/quality-rails

Quality-rails scaffolding and — since RI-3-002 (RI-N4) — the typed quality-rails evaluator: the single authoritative producer of check verdicts for the checks it owns.

Evaluator (RI-N4)

Every verdict is typed and fail-closed:

{ status: 'passed' | 'failed' | 'blocked' | 'error' | 'not-applicable',
  checkId, checkVersion, subject, reason }

Missing implementations, missing inputs, unknown check ids, process errors, timeouts, and malformed probe output can never become passed or an unqualified skip — they surface as blocked/error with a reason (vocabulary mirrors MACP's GateStatus discipline).

• Check definitions live as data with a version and a sha256 content digest (definitionDigest); every recorded verdict names the definition version that produced it.
• Check sets are selected per subject kind (node, python, rust, monorepo, unknown) via the versioned, digested check-set policy — this repository (a monorepo subject) does not share the node template's file list.
• Shell probes stay thin adapters: the TS evaluator invokes them and owns the verdict parsing (e.g. QC-20's planted-commit probe).

Owned checks

check id	canonical check	mechanism
qc-19-rails-files-present	QC-19	typed absorption of the former presence-only check/doctor loop
qc-20-enforcement-verify	QC-20	thin shell adapter (framework verify.sh); verdict parsing owned here

The canonical check ids QC-1..QC-21 and their dispositions are defined in docs/release-integrity/probe-inventory.md (the RI-3-001 inventory — the evaluator's input, not its output).

Usage

# CLI (same typed report as the programmatic API)
node dist/cli.js quality-rails evaluate --project <path> [--probe-path <verify.sh>] [--json]
node dist/cli.js quality-rails check --project <path> [--json]   # QC-19 only, fail-closed exit

import { evaluateSubject } from '@mosaicstack/quality-rails';

const report = await evaluateSubject({ subjectPath: '/path/to/project' });
// report.state: 'passed' | 'failed' | 'blocked' | 'error'

pnpm verify:release invokes this evaluator as its quality-rails stage (canonical-only stage, QC-19 on the monorepo subject).

Scaffolding (pre-existing)

init scaffolds rails files per detected kind/profile; doctor is advisory and reports typed states.