Quality Gates

Purpose

Define the canonical release-quality gates for DSAMbayes v1.3.3, including commands, pass/fail criteria, and evidence requirements.

Audience

• Maintainers preparing a release candidate
• Reviewers signing off release readiness
• Engineers running local pre-merge quality checks

Gate Matrix

Gate Definitions

QG-1 Lint

Command:

Rscript scripts/check.R --lint

Fail conditions:

• Non-zero exit code
• Any lint issue reported
• Any SKIP: output

QG-2 Style

Command:

Rscript scripts/check.R --style

Fail conditions:

• Non-zero exit code
• Any file reported as requiring reformat
• Any SKIP: output

QG-3 Unit Tests

Command:

Rscript scripts/check.R --test

Fail conditions:

• Non-zero exit code
• Any test failure or error

QG-4 Stan Release Evidence

Command:

Rscript scripts/check.R --stan-release-evidence

Fail conditions:

• Non-zero exit code
• Any high-budget Stan evidence test failure
• Any unresolved diagnostic-threshold failure

QG-5 Package Check

Command:

_R_CHECK_FORCE_SUGGESTS_=false \
  R -q -e 'rcmdcheck::rcmdcheck(args = c("--no-manual"), error_on = "warning")'

Fail conditions:

• Any ERROR
• Any WARNING for release sign-off

Escalation condition:

• Any NOTE must be reviewed and explicitly accepted with rationale.

Operational note:

• Local package checks do not force Suggests because DSAMdecomp is an optional decomposition-only dependency and the upstream available package is telemetry-enabled. Decomposition-specific checks should be run separately against an approved telemetry-free DSAMdecomp install.

QG-6 Runner Smoke: Validate

Command:

Rscript scripts/dsambayes.R validate \
    --config config/blm_timeseries.yaml \
    --run-dir results/quality_gate_validate

Fail conditions:

• Non-zero exit code
• Missing results/quality_gate_validate/00_run_metadata/config.resolved.yaml
• Missing results/quality_gate_validate/00_run_metadata/config.compiled.yaml

QG-7 Runner Smoke: Run

Command:

Rscript scripts/dsambayes.R run \
    --config config/blm_timeseries.yaml \
    --run-dir results/quality_gate_run

Fail conditions:

• Non-zero exit code
• Missing results/quality_gate_run/00_run_metadata/config.resolved.yaml
• Missing results/quality_gate_run/00_run_metadata/config.compiled.yaml
• Missing results/quality_gate_run/20_model_fit/model.rds
• Missing results/quality_gate_run/30_post_run/fitted.csv
• Missing results/quality_gate_run/30_post_run/observed.csv
• Missing results/quality_gate_run/40_diagnostics/diagnostics_report.csv

QG-8 Docs Build Check

Command:

python3 docs-site/build_content.py
(cd docs-site && hugo --cleanDestinationDir)

Fail conditions:

• Non-zero exit code
• docs-site/build_content.py fails before content mirroring completes
• Hugo build aborts before site generation
• Missing docs-site/public/index.html

Command Reference

Recommended environment setup before running gates:

# Navigate to your local DSAMbayes checkout and select the host library
cd /path/to/DSAMbayes
source scripts/r-library-path.sh
dsambayes_set_r_library host
mkdir -p "$R_LIBS_USER" .cache
export XDG_CACHE_HOME="$PWD/.cache"
export _R_CHECK_FORCE_SUGGESTS_=false

Optional consolidated local gate (does not replace all release gates):

Rscript scripts/check.R --docs
Rscript scripts/check.R --smoke
Rscript scripts/check.R --stan-recovery
Rscript scripts/check.R --stan-release-evidence
Rscript scripts/check.R --release
Rscript scripts/check.R --all

Profile meanings:

• --docs runs the local docs/link sanity helper against README and the tracked docs surfaces.
• --smoke runs the fast unit path plus the minimal Stan-backed smoke subset.
• --stan-recovery runs the full-gated DGP coefficient-recovery file only, intended for targeted numerical evidence refreshes.
• --stan-release-evidence runs high-budget pooled and hierarchical Stan checks with diagnostic thresholds for release-candidate evidence.
• --release runs lint, style, unit tests, minimal Stan smoke, docs sanity, and coverage.
• --all remains the legacy lint + style + tests + coverage profile.

None of these profiles replaces rcmdcheck, runner smoke checks, or the docs-site build.

Evidence Requirements

Minimum evidence bundle per release candidate:

1. Full terminal output and exit code for each gate QG-1 to QG-8.
2. Runner smoke artefacts under results/quality_gate_validate/.
3. Runner smoke artefacts under results/quality_gate_run/.
4. rcmdcheck summary with explicit handling of NOTEs.
5. Confirmation that no gate result is SKIP.

Evidence review should reference:

• Release Readiness Checklist
• Release Evidence Pack
• Release Sign-off Template

Failure and Escalation Rules

1. Any gate failure blocks release tagging.
2. Do not proceed to sign-off with unresolved ERROR or WARNING.
3. NOTEs require written rationale and reviewer acceptance.
4. If a gate fails due to environment setup, fix the environment and re-run the full affected gate. DSAMdecomp absence alone is not a blocker for QG-4 because the canonical package check flow treats it as an optional Suggests dependency.
5. If a gate fails due to product code, raise a remediation change and re-run from QG-1.

Sign-off Criteria

Release sign-off requires all of the following:

1. QG-1 to QG-8 passed.
2. No SKIP outcomes across mandatory gates.
3. Evidence bundle completed and reviewed.
4. Final decision recorded in sign-off-template.md.