# @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.