Checks And Validation
This page catalogs every local check, test, lint, and build-validation command you can run before committing. It also maps them to the CI gates they mirror.
Run the Quick Pre-Commit commands before every push. Use the area-specific commands when you touch a particular subsystem.
Quick Pre-Commit (~60s total)
These four commands mirror what CI runs on every PR. If they all pass, your change is clean.
# 1. Rust runtime tests (~30s)
cargo test --manifest-path ./runtime/Cargo.toml
# 2. Renderer TypeScript typecheck (~5s)
npm --prefix ./Frontend/HolonClient run typecheck
# 3. Renderer ESLint (~3s)
npm --prefix ./Frontend/HolonClient run lint
# 4. Renderer unit/component tests (~10s)
npm --prefix ./Frontend/HolonClient run test -- --run
Command Catalog
HolonClient — Renderer (React / Vite)
| Command | What It Runs | Category | In CI? |
|---|---|---|---|
npm --prefix ./Frontend/HolonClient run typecheck | tsc --noEmit — strict TypeScript type-check | typecheck | ✅ ci.yml |
npm --prefix ./Frontend/HolonClient run lint | eslint . — flat config (TS parser, react-hooks, react-refresh, Tauri import boundary) | lint | ✅ ci.yml |
npm --prefix ./Frontend/HolonClient run lint:host-boundary | depcruise — no direct @tauri-apps imports outside Infrastructure/host/ | architecture | ❌ manual only |
npm --prefix ./Frontend/HolonClient run test -- --run | vitest — jsdom, globals, React plugin | unit test | ✅ ci.yml |
npm --prefix ./Frontend/HolonClient run check:chunks | Bundle chunk size budget enforcement | build | ❌ manual only |
npm --prefix ./Frontend/HolonClient run check:workflow-contract | Validates workflow-contract Zod schema is importable | schema | ❌ manual only |
npm --prefix ./Frontend/HolonClient run proof:elegy-contract-consumption | Validates Elegy contract schema compatibility (requires --contracts <dir>) | contract | ❌ triggered via bootstrap |
npm --prefix ./Frontend/HolonClient run e2e | playwright test — desktop Chrome E2E, base URL localhost:4173 | e2e | ❌ manual only |
npm --prefix ./Frontend/HolonClient run e2e:summary | Summarizes Playwright JSON results | reporting | ❌ manual only |
npm --prefix ./Frontend/HolonClient run build | vite build — production renderer bundle | build | ❌ (staged in packaging step) |
Config files:
Frontend/HolonClient/vitest.config.ts— jsdom environment, globals, React plugin, path aliasesFrontend/HolonClient/playwright.config.ts— desktop Chrome, 60s timeout, 2 CI retries, HTML + JSON reportersFrontend/HolonClient/eslint.config.js— ESLint 9 flat config, TypeScript parser, architectural import boundary ruleFrontend/HolonClient/tsconfig.json— strict mode, ESNext modules, noEmit, path aliases
HolonDesktop — Tauri Shell
| Command | What It Runs | Category | In CI? |
|---|---|---|---|
npm --prefix ./Frontend/HolonDesktop run test | Node --test runner → desktopHostLifecycle/*.test.js (2 files) | unit test | ✅ ci.yml |
npm --prefix ./Frontend/HolonDesktop run test:real-desktop | Playwright real-desktop E2E — launches actual Tauri window, specs/startup.real-desktop.spec.ts | e2e | ❌ manual only |
npm --prefix ./Frontend/HolonDesktop run verify:workspace-parity | Validates Tauri command registration parity across main.rs handler macro, permissions allow-list, and capability bindings | architecture | ❌ manual only |
npm --prefix ./Frontend/HolonDesktop run verify:packaging-readiness | Audits tauri.conf.json, icons, renderer dist, Cargo.toml features, writes readiness report | build | ✅ ci.yml |
npm --prefix ./Frontend/HolonDesktop run package:stage:win-x64 | Builds HolonClient renderer + validates staged packaging inputs | build | ✅ ci.yml |
Note: HolonDesktop does not have its own lint or typecheck scripts. TypeScript config in tests/real-desktop/tsconfig.json covers only test files. Desktop script validation relies on CI's build step.
Config files:
Frontend/HolonDesktop/tests/real-desktop/playwright.real-desktop.config.ts— 180s timeout, single worker, retain-on-failure video/trace
Rust Runtime (runtime/)
| Command | What It Runs | Category | In CI? |
|---|---|---|---|
cargo build --manifest-path ./runtime/Cargo.toml | Builds all 13 workspace crates | build | ✅ (implicit in test) |
cargo test --manifest-path ./runtime/Cargo.toml | All Rust unit + integration tests across 13 crates | unit test | ✅ ci.yml |
cargo test -p <crate> | Narrow to one specific crate | unit test | ❌ (dev tool) |
Workspace crates: holon-adapter-core, holon-api-adapter, holon-planning-adapter, holon-protocol, holon-store, holon-runtime-core, holon-transport, holon-runtime-client, holon-cli, holon-structured-output, holon-workflow, holon-crystallization, holon-executor
Known gaps: No cargo clippy or cargo fmt --check in CI. No cargo audit/cargo deny for dependency vulnerability scanning. No rust-toolchain.toml for local dev consistency.
Docs (docs/system/, docs/website/)
| Command | What It Runs | Category | In CI? |
|---|---|---|---|
./scripts/check-doc-authoring.ps1 | Validates YAML frontmatter on all docs/system/**/*.md — 8 required fields, allowed values for status/doc_kind, sidebar resolution, manifest path existence | docs | ✅ ci.yml |
./scripts/check-doc-links.ps1 | Resolves all internal markdown links under docs/system/**; forbids links into docs/todo/ | docs | ✅ ci.yml |
./scripts/check-no-committed-env.ps1 | Guards against committed .env / .env.production under Frontend/HolonClient | security | ❌ manual (release-prep) |
npm run docs:build | docusaurus build — production docs website build | build | ✅ ci.yml |
Version & Release
| Command | What It Runs | Category | In CI? |
|---|---|---|---|
./scripts/verify-version.ps1 | Validates version consistency across 15+ files (Cargo.toml, package.json, package-lock.json, tauri.conf.json, changelog.md, Cargo.lock) | release | ✅ ci.yml, release.yml |
./scripts/verify-version.ps1 -Tag vX.Y.Z | Same as above, but enforces a specific expected version | release | ✅ release.yml |
./scripts/export-release-notes.ps1 | Extracts changelog entry for a version to a file | release | ✅ release.yml |
npm --prefix ./Frontend/HolonDesktop run verify:packaging-readiness | Audits tauri.conf.json, icons, renderer dist, Cargo.toml features | release | ✅ ci.yml |
Elegy Bridge
| Command | What It Runs | Category | In CI? |
|---|---|---|---|
./scripts/validate-elegy-bridge-freeze.ps1 | Scans repo for legacy NuGet/GitHub-Packages bridge references (zero-tolerance) | contract | ✅ bridge-freeze, bootstrap-proof |
./scripts/bootstrap-elegy-distribution.ps1 -Force | Downloads + installs + validates pinned Elegy release, proves contract consumption | contract | ✅ bootstrap-proof |
./scripts/prove-holon-consumption.ps1 | Validates install receipt + Elegy contract schema compatibility via tsx proof | contract | ❌ (called by bootstrap) |
Config: scripts/elegy-bootstrap.config.json — pins Elegy tag (v1.3.2), CLI/wrapper surfaces, proof contract entries.
WS5 Scripts (Milestone Tooling)
| Command | What It Runs | Category | In CI? |
|---|---|---|---|
npm --prefix ./Frontend/HolonClient run ws5:auth-nav:defect-gate | Runs targeted vitest suites for auth-navigation regressions, writes artifact JSON | regression gate | ❌ manual only |
npm --prefix ./Frontend/HolonClient run ws5:host-matrix:artifact | Generates host matrix documentation artifact (JSON + Markdown) | artifact | ❌ manual only |
npm --prefix ./Frontend/HolonClient run ws5:rollout | Toggles runtime config env vars for WS5 rollout stages | config | ❌ manual only |
CI Workflows (GitHub Actions)
CI (ci.yml) — Runs on PR and push (non-tags)
Four parallel jobs, ~20-30 min:
| Job | Runner | Steps |
|---|---|---|
| rust-runtime | ubuntu | Checkout → Rust 1.83.0 → Restore cache → cargo test |
| holon-client | ubuntu | Checkout → Node 20.19.0 → npm ci → lint → typecheck → test -- --run |
| holon-desktop | windows | Checkout → Node 20.19.0 → npm ci → package:stage:win-x64 → test → verify:packaging-readiness |
| docs-and-version | ubuntu | Checkout → Node 20.19.0 → npm ci → verify-version.ps1 → check-doc-authoring.ps1 → check-doc-links.ps1 → docs:build |
Release (release.yml) — Runs on v* tag push
Two sequential jobs:
- release-windows (120 min): Checkout → verify version → stage packaging → build desktop installer (signed) → build CLI → smoke test both → upload assets → publish release
- post-publish-verify (ubuntu): Download published assets → verify manifest → verify checksums
Preview Release (preview-release.yml) — Runs on push to master
Builds unsigned preview installer, publishes to preview GitHub release.
Elegy Bridge Freeze (elegy-bridge-freeze.yml)
Runs on every PR and push to main/master. Fast (~1 min): validates no legacy Elegy NuGet/GitHub-Packages bridge references exist.
Elegy Bootstrap Proof (elegy-bootstrap-proof.yml)
Path-filtered: triggers only when Elegy-related files change. Validates bridge freeze, then bootstraps Holon from pinned Elegy release.
VS Code Tasks
Configured in .vscode/tasks.json:
| Task | Description |
|---|---|
playwright-e2e | Run Playwright E2E tests from HolonClient |
checkpoint: holon-client tests | Run focused vitest suite (DesktopHomePage, WorkspaceShellLayout, workspaceRouteCanonicalization) |
checkpoint: holon-client typecheck | Run HolonClient TypeScript typecheck |
checkpoint: holon-client lint | Run HolonClient ESLint |
Known Gaps
| Gap | Impact | Notes |
|---|---|---|
| No pre-commit hooks | Can commit broken code; everything relies on CI | Consider adding lefthook or husky |
No cargo clippy in CI | Rust lint regressions undetected | Add to ci.yml rust-runtime job |
No cargo fmt --check | Inconsistent Rust formatting | Add with rustfmt.toml |
No cargo audit/cargo deny | Unscanned Rust dependency vulns | Add scheduled workflow |
No rust-toolchain.toml | Local dev may use different Rust version than CI | Add file pinning 1.83.0 |
| HolonDesktop: no lint/typecheck | Type errors in desktop scripts undetected | Needs own tsconfig.json + eslint config |
| HolonDesktop: minimal test coverage | Only 2 Node test files cover the shell | Needs expansion |
| No CodeQL / security scanning | No automated vulnerability detection | Add CodeQL workflow |
| Real-desktop E2E not in CI | Desktop shell E2E only testable locally | Could run on self-hosted Windows runner |
| No unified local "run all" script | Fragmented pre-commit experience | Consider scripts/pre-commit.ps1 orchestrator |
| Dependabot: security-only updates | Non-security dependency drift goes unnoticed | Consider expanding update types |
| Dependabot: missing ecosystems | No cargo, github-actions, docs/website coverage | Add missing ecosystem entries |
Script Quality Baseline
All scripts/ validation scripts follow these conventions:
Set-StrictMode -Version Latest— strict PowerShell parsing$ErrorActionPreference = 'Stop'— halt on any cmdlet failure- Explicit exit codes (
0= success,1= failure,2= prerequisite missing) - No hardcoded user paths; everything resolved relative to
$PSScriptRoot try/finallyhygiene for temp directory and environment variable cleanup
Script health was audited on 2026-06-09. Removed: prove-saastools-consumption.ps1 (duplicate), check-canonical-docs-sync.ps1 (stale post-migration guard). Removed stale .vscode/tasks.json entries for deleted .NET plugin tests and scratch tmp: tasks.
Adding A New Check
When adding a new validation command or script:
- Add the npm/cargo script to the relevant
package.jsonorCargo.toml - Wire it into CI in
.github/workflows/ci.ymlif it should gate every PR - Add it to this document under the appropriate category
- Add it to the sidebar if it warrants a dedicated guide page
- Run
./scripts/check-doc-authoring.ps1if you add/changed any docs metadata - Run
./scripts/check-doc-links.ps1if you added cross-references