ADR 0007: Index Release Gate Policy
ADR 0007: Index Release Gate Policy
Status: Accepted for architectural direction.
Date: 2026-05-11.
Context
UWScrape will publish versioned runtime index artifacts.
The backend will load published index artifacts and serve student-facing queries.
A malformed or poorly validated index can produce misleading academic pathway answers.
The scraper pipeline intentionally preserves unparsed requirements.
Some unparsed requirements are acceptable in early versions.
Some missing or broken data is not acceptable.
The project needs a release gate that separates build completion from publication approval.
Publication approval should be explicit.
Publication approval should be reviewable.
Publication approval should not depend on hidden judgment.
The release gate must support early development without pretending the index is perfect.
The release gate must become stricter as parser coverage improves.
Decision
UWScrape will use a validation-based release gate for every published index.
The release gate is evaluated after fetch, parse, validate, and index build.
The release gate must read machine-readable validation output.
The release gate must read build metadata.
The release gate must read patch application output.
The release gate must produce a release decision record.
The release decision record must be stored with the published index.
The release decision record must include the decision status.
The release decision record must include accepted warnings.
The release decision record must include reviewer notes.
The release decision record must include artifact hashes.
The release decision record must include source catalog metadata.
The release decision record must include parser and index schema versions.
The release decision status may be approved.
The release decision status may be approved_with_warnings.
The release decision status may be rejected.
The backend may serve approved indexes.
The backend may serve approved_with_warnings indexes.
The backend must expose warning status through metadata endpoints.
The backend must not serve rejected indexes by default.
The backend must not serve indexes with missing release decision records once release gates are implemented.
Required Gate Inputs
The gate requires build-metadata.json.
The gate requires validation-summary.json.
The gate requires validation-report.md.
The gate requires patch_applications.jsonl when patches were configured.
The gate requires the SQLite index file.
The gate requires index metadata to be readable.
The gate requires source catalog metadata.
The gate requires source snapshot hash metadata.
The gate requires parser version metadata.
The gate requires index schema version metadata.
The gate requires validation status metadata.
The gate requires unparsed requirement counts.
The gate requires failed request counts.
The gate requires item count reconciliation.
Blocking Conditions
Missing catalog metadata blocks release.
Unsupported index schema version blocks release.
Unreadable SQLite index blocks release.
Missing validation summary blocks release.
Validation status failed blocks release.
Any validation finding with level blocker blocks release.
Missing required schemas block release.
Fetch summary count lower than expected count blocks release.
Missing detail records for required item types block release unless explicitly waived.
Invalid raw JSON blocks release.
Invalid parsed JSONL blocks release.
Duplicate pids within an item type block release.
Broken requirement expression parent references block release.
Broken requirement condition references block release.
Patch schema errors block release.
Duplicate patch ids block release.
Required patch target misses block release.
Index build metadata mismatch blocks release.
Source snapshot hash mismatch blocks release.
Warning Conditions
Unparsed requirements are warnings unless configured otherwise.
Unresolved course links are warnings initially.
Unresolved credential links are warnings initially.
Asymmetric cross-listings are warnings initially.
Asymmetric antirequisites are warnings initially.
Unexpected optional source fields are warnings.
Parser low-confidence records are warnings.
Partial average parsing is a warning.
Unknown academic progress values are warnings unless common enough to indicate parser failure.
Patch target misses for optional patches are warnings.
High unparsed count in credential-completion fields is a high-priority warning.
High unparsed count in enrollment fields is a high-priority warning.
Warnings must appear in the release decision record when accepted.
Accepted warnings must not disappear from validation reports.
Initial Thresholds
The first release gate should not block on total unparsed requirement count.
The first release gate should block on missing required raw records.
The first release gate should block on invalid index structure.
The first release gate should block on broken internal references.
The first release gate should block on required patch misses.
The first release gate should warn on unresolved source links.
The first release gate should warn on unparsed high-impact fields.
The first release gate should report unparsed counts by item type.
The first release gate should report unparsed counts by source field.
The first release gate should report unparsed counts by faculty when available.
Thresholds may be tightened after parser coverage improves.
Threshold changes should be reviewed.
Threshold changes should be recorded in validation policy files.
Release Decision Record
The release decision record should be named release-decision.json.
The release decision record should have a matching release-decision.md.
The JSON record should be machine-readable.
The Markdown record should be reviewer-readable.
The record should include decision.
The record should include decided_at.
The record should include reviewer.
The record should include catalog_id.
The record should include catalog_title.
The record should include catalog_slug.
The record should include index_schema_version.
The record should include parser_version.
The record should include source_snapshot_hash.
The record should include sqlite_hash.
The record should include validation_summary_hash.
The record should include accepted_warning_ids.
The record should include accepted_warning_summary.
The record should include known_limitations.
The record should include publication_notes.
The record should include source_urls.
The record should not contain secrets.
Reviewer Checklist
The reviewer confirms catalog id.
The reviewer confirms catalog title.
The reviewer confirms catalog date range.
The reviewer confirms expected item counts.
The reviewer confirms failed request count.
The reviewer confirms validation blocker count is zero.
The reviewer confirms required patches applied.
The reviewer confirms patch misses are understood.
The reviewer confirms parser coverage summary is acceptable.
The reviewer confirms high-impact unparsed fields are understood.
The reviewer spot-checks representative courses.
The reviewer spot-checks representative credentials.
The reviewer spot-checks one complex Faculty of Mathematics credential.
The reviewer spot-checks source references for a parsed requirement.
The reviewer spot-checks source references for an unparsed requirement.
The reviewer confirms backend compatibility metadata.
The reviewer confirms publication target path.
The reviewer records known limitations.
Alternatives Considered
Alternative 1: Publish Any Successful Build
The project could publish every index that successfully builds.
This would move quickly.
However, a successful build can still contain serious data gaps.
This alternative is rejected.
Alternative 2: Require Perfect Parser Coverage
The project could require zero unparsed requirements before publication.
This maximizes confidence in one sense.
However, Waterloo requirements contain complex natural language.
Perfect coverage would delay useful development indefinitely.
This alternative is rejected.
Alternative 3: Manual Review Without Machine Gate
The project could rely on human review alone.
Human review is necessary.
However, human review without machine gates is inconsistent and hard to reproduce.
This alternative is rejected.
Consequences
Publication becomes explicit.
Backend startup can trust release metadata.
Warnings remain visible instead of being normalized away.
The project can ship useful indexes before perfect parser coverage.
The validation policy becomes part of product trust.
The team must maintain validation policy files.
The team must avoid treating approved_with_warnings as perfect.
Follow-Up
Define validation policy file format.
Define release decision file schema.
Add backend startup checks for release decision status.
Add CLI support for release decision generation after implementation begins.