feat(quality-rails): typed evaluator absorbs QC-19/QC-20; verify-release wiring (RI-3-002, #1275) (#1308)

2026-08-18 17:54:47 +00:00
parent ff45f7b5d0
commit 245e0c427d
13 changed files with 1661 additions and 58 deletions
@@ -0,0 +1,63 @@
+# @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
+
+```sh
+# 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
+```
+
+```ts
+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.