Engineering system
Code reaches production through one pipeline, shared by human and AI contributors: plan, implement with tests, a focused safety audit, an independent AI code review against the clinical invariants, then 20+ CI workflows and 40+ one-way ratchets. Ratchets let quality move in one direction only — a file may shrink but not grow past its limit, an any count may fall but not rise, a snapshot of exceptions may only lose entries. Guards are themselves tested: a check that cannot observe its own failure is treated as a defect.
The change pipeline
- Plan
- What happens
- Restate the task, check open pull requests touching the same paths, pick the smallest change set
- Implement
- What happens
- Code and tests together; targeted tests for the change
- Audit
- What happens
- A focused pass for security holes, data loss, clinical-invariant breaches and unhandled errors
- Commit and pull request
- What happens
- Conventional commits; the pull request states outcome, invariants, changed surface, evidence and exclusions
- AI code review
- What happens
- An independent reviewer checks the change against the pipeline and the clinical safety contract; every finding is fixed or rebutted with evidence, and any push after review needs a new review
- CI
- What happens
- The complete profile on the merge candidate; a red check blocks merge
- Merge
- What happens
- Squash; never to main directly, never force-pushed, never an administrator override
| Stage | What happens |
|---|---|
| Plan | Restate the task, check open pull requests touching the same paths, pick the smallest change set |
| Implement | Code and tests together; targeted tests for the change |
| Audit | A focused pass for security holes, data loss, clinical-invariant breaches and unhandled errors |
| Commit and pull request | Conventional commits; the pull request states outcome, invariants, changed surface, evidence and exclusions |
| AI code review | An independent reviewer checks the change against the pipeline and the clinical safety contract; every finding is fixed or rebutted with evidence, and any push after review needs a new review |
| CI | The complete profile on the merge candidate; a red check blocks merge |
| Merge | Squash; never to main directly, never force-pushed, never an administrator override |
Continuous integration
- Typecheck
- Purpose
- Five TypeScript project slices, the route manifest check and the architecture facts check
- Ratchet lints
- Purpose
- 40+ one-way lints (below)
- RLS and scoped-access lints
- Purpose
- Tenant isolation, statically
- Tests
- Purpose
- 3,300+ test files in unit and heavy tiers, with per-file time budgets
- Integration
- Purpose
- Migrations on a real database, the shadow migration-v2 run, the research plane, the adversarial cross-tenant suite
- Build, audit, SBOM
- Purpose
- Both production builds, dependency audit, a software bill of materials
- Docker smokes
- Purpose
- Hermetic container smoke tests for the application, the imaging pre-processor and the document renderer
- End-to-end
- Purpose
- 18 browser specs, including visual fixtures
- Evaluations
- Purpose
- Copilot and Scribe evaluation workflows; the perio recognition benchmark
- Security
- Purpose
- CodeQL and Semgrep
| Job | Purpose |
|---|---|
| Typecheck | Five TypeScript project slices, the route manifest check and the architecture facts check |
| Ratchet lints | 40+ one-way lints (below) |
| RLS and scoped-access lints | Tenant isolation, statically |
| Tests | 3,300+ test files in unit and heavy tiers, with per-file time budgets |
| Integration | Migrations on a real database, the shadow migration-v2 run, the research plane, the adversarial cross-tenant suite |
| Build, audit, SBOM | Both production builds, dependency audit, a software bill of materials |
| Docker smokes | Hermetic container smoke tests for the application, the imaging pre-processor and the document renderer |
| End-to-end | 18 browser specs, including visual fixtures |
| Evaluations | Copilot and Scribe evaluation workflows; the perio recognition benchmark |
| Security | CodeQL and Semgrep |
Ratchets
- Size and type safety: file length,
anycount, bundle budget. - Boundaries: Docker runtime image, imaging loader, artifact server, audio session, voice adapters, clinical mock imports.
- Clinical vocabulary: perio staging terms, Scribe completeness terms, voice phrase coverage, evidence copy.
- Governance: QMS design-history coverage, regulatory feature registry, agent-instruction parity, CI-to-script parity.
- Content: duplicate JSON keys, missing i18n keys, retired-brand spread.
A baseline may be regenerated only as a deliberate, reviewed change — locking in an improvement or a planned move of the bar — never to silence a failure. The ratchet that keeps CI and the npm script in agreement exists because a lint once ran locally and never in CI.
Verifying the guards
The pipeline records, by incident, the ways a green check can be empty — and requires the opposite of each:
- Break what a guard protects and watch it fail — and read which branch rejected it, because an earlier branch can make a test pass for the wrong reason.
- Mutate the behaviour, not the token: removing a literal only proves the assertion reads that literal.
- Prove a compliant case passes, so guards do not teach people to weaken them.
- Write down what each guard cannot see.
- Read the exit code and the error line of a run, not its pass count — a suite that failed to load can report a confident number.
This specification follows the same rule: its ID-boundary test, its facts drift check, its ADR classification check and its diagram-routing check were each broken deliberately and observed to fail before being trusted.
docs/pipeline/core.mddocs/pipeline/codex-review.md.github/workflows/ci.ymlscripts/lint-*.tsscripts/test-tiers.ts