home · /governance/production-hygiene

Production hygiene package

v1.0

Path: /governance/production-hygiene.md · v1.0 · 2026.05

This document specifies the operational hygiene the runtime repo follows. The standards listed here are normal expectations for shipped open-source infrastructure. Their absence is read by serious engineering reviewers as immaturity, regardless of code quality.

The list is short on purpose. Hygiene is not differentiation; it is the floor.

Semantic versioning

PROACTIVE and SentinelOS follow SemVer 2.0.

MAJOR version: incompatible API or detection-output schema changes.
MINOR version: feature additions, new detectors, new configuration options.
PATCH version: bug fixes, performance improvements, dependency bumps.

A change to a PROACTIVE feature definition (F1–F4) is a MAJOR version bump even if the API surface is unchanged, because adopters' downstream calibration depends on the feature semantics.

Public API surfaces are explicitly enumerated in API.md. Anything not enumerated is considered internal and may change between minors.

CHANGELOG

Every release has an entry in CHANGELOG.md. The format follows Keep a Changelog.

Sample entry:

## [1.2.0] — 2026-08-15

### Added
- F5 (claim-coverage ratio) as an experimental feature behind `--experimental f5`.
- `sentinel diagnose` subcommand for inspecting borderline classifications.
- Spec-first workload to the published benchmarks suite.

### Changed
- F2 acceptance window default lowered from 14 to 7 days based on benchmark calibration.
- `make verify` runtime reduced from 73s to 58s.

### Fixed
- False positive on Cursor sessions where the agent appended status lines to a separate scratch buffer.

### Deprecated
- `sentinel scan --legacy-output`: will be removed in 2.0.

### Security
- None.

A release with no CHANGELOG entry is not a release. CI rejects tags without an accompanying entry.

Pinned dependencies

The repository uses uv with uv.lock for Python dependencies and package-lock.json for Node dependencies. Both lockfiles are committed.

No floating versions in production manifests. Every dependency has an exact version. Dependabot or Renovate updates are reviewed individually with the relevant tests run before merge.

The reasoning: make verify must be byte-for-byte reproducible against the published hashes. Floating versions break that property.

A flake.nix (Q3 2026 candidate, see roadmap) extends this guarantee to system-level dependencies.

CI gates

Every pull request must pass:

Lint — ruff for Python, eslint for Node. Strict mode; no --ignore for new code.
Type-check — mypy strict for Python; tsc strict for Node.
Test suite — 62/62 Constitution, 212/212 PROACTIVE, 88+/88+ SentinelOS, plus any new tests for the change.
Reproduce-path verify — make verify on Mac, Linux, Windows.
Benchmark regression check — if any operational metric regresses by more than 10%, the PR is blocked pending discussion. If a metric improves, that is noted in the CHANGELOG.
Documentation coverage — new public API surfaces require corresponding documentation updates. CI runs make docs-coverage against a target percentage.
CHANGELOG entry — any non-trivial change requires an entry. CI inspects.

Failing any gate blocks merge. Override requires maintainer approval with a documented justification in the PR description.

Branch protection on `main`

main is the canonical released branch. All shipped artifacts derive from a tagged commit on main.
Force-push disabled.
Required reviews: 1 maintainer for routine changes; 2 for changes to PROACTIVE feature definitions or detection-output schemas.
All CI must pass before merge.
Squash-merge is the default; merge-commits are reserved for feature-branch merges from external contributors when commit-by-commit history matters.

Release procedure

Bump version in pyproject.toml and package.json per SemVer.
Update CHANGELOG.md.
Run make verify locally and confirm green.
Run make benchmarks and update benchmarks/[version]/.
Tag the commit (vMAJOR.MINOR.PATCH).
Push tag. CI publishes the wheel, the npm package, and a GitHub release with the CHANGELOG entry as release notes.
Sign the release artifacts and update /provenance/manifest.json.
Announce in the project's quarterly amendment.

A release that skips step 4 (benchmarks) is labeled "no-benchmark release" in the GitHub release notes. We publish the label so adopters can decide whether to skip.

Issue and PR templates

.github/ISSUE_TEMPLATE/ contains:

bug.md — bug reports with reproduce steps, expected vs. observed, environment, sentinel diagnose output where relevant.
false-positive.md — false positives with the scan output, the transcript (anonymized), and the reasoning for why it should not have triggered.
false-negative.md — false negatives with the scan output, the transcript, the reasoning for why it should have triggered.
feature-request.md — feature requests with use case, current workaround, and the smallest possible change that would address it.
reproducibility.md — make verify failures or hash mismatches, treated as P0.

.github/PULL_REQUEST_TEMPLATE.md requires: - Description of the change. - CHANGELOG impact (or "no changelog impact" with reason). - Benchmark impact (run if mechanical change to detection code). - New tests added or rationale for not adding. - Linked issue, if any.

Security disclosure

SECURITY.md at the repo root specifies: - security@coreyalejandro.com as the disclosure address. - 90-day disclosure window from acknowledgment. - Bounty terms (see /governance/bounty.md). - Out-of-scope items (the documented evasion paths in the threat model).

Maintenance burden honesty

The current maintenance population is one person (the founder). Hygiene standards above are real expectations; missed deadlines on hygiene tasks are not unethical, but they need to be visible.

The runtime repo's STATUS.md is updated weekly and publishes: - Open PRs older than 7 days. - Open issues older than 30 days. - Tests currently flaky or skipped. - Dependency vulnerabilities pending update.

A reviewer evaluating maintainability of the project should look at STATUS.md first. Hygiene that is documented but not observed is worse than hygiene that is acknowledged as aspirational.