DarDev Ops startup awareness runs a fast validator subset before you open the console, start the platform bus, or assume local scripts match production contracts. Instead of discovering manifest drift, bus route parity gaps, or JSON Schema violations only when a full CI validate-all job fails, setup-local.sh, npm run dev predev hooks, and optional deploy steps execute startup-check.sh and surface WARN logs plus a SetupPanel summary in Ops Home.
The goal is early signal for developers and coding agents: fix non-fatal drift during boot, reserve --strict mode for CI and pre-deploy where errors fail the pipeline. Status persists to data/ops-startup-status.json so the Ops UI can show tunnel hints, secret file presence, and validator warnings alongside SSH tunnel setup—the same file startup-check writes on every run.
The problem startup awareness solves
Before SA-S1, ops-validate and twenty-two CI gates ran on demand. A developer could npm run dev in the Ops console, hit Configure, and interact with connectors whose manifest graphs no longer matched the integration registry. Platform bus could ListenAndServe with route catalog drift silent until an integration action 404'd. Scripts-policy violations—Node one-offs outside bash, Python, Go policy—accumulated in scripts/ without a lightweight check.
Full validate-all remains the authority for release gates. Startup awareness is the subset cheap enough for every boot: manifests, connectors, bus-parity warn, duplicate ops/lib modules warn, scripts-language warn, solution-registry warn, json-schema error in strict else warn, json-format warn, tunnel health warn, ops/.env.local presence warn.
Commands and modes
- bash scripts/ops/validate/startup-check.sh — warn-only local default
- bash scripts/ops/validate/startup-check.sh --strict — CI and pre-deploy; errors fail exit code
- bash scripts/ops/validate/startup-check.sh --skip-tunnel — skip 127.0.0.1:3100/health when bus not running
- cd ops && npm run validate:startup — Ops package wrapper
- bash scripts/ops/validate/ops-validate.sh startup-awareness-status --validate --gate SA-1 — sprint gate
Tracker stories SA-001 through SA-008 live in ops/tracker/startup-awareness.json. Exit criteria: all milestones gate_ready and startup-check --strict green in CI. This complements Ops maturity V1.0.0—security and Swarm gates assume contracts stay valid at runtime, not only on merge.
What each check validates
Manifests (error): P1 solution manifests under solutions/ and ops/solutions/manifests/ parse and reference known connector types. Connectors (error): registry graphs match manifest declarations—no orphan capability IDs. Bus-parity (warn): manifest HTTP routes align with platform bus route catalog; mismatches log before first API call.
Duplicate-modules (warn): catches ops/lib .js and .ts pairs that confuse imports. Scripts-language (warn): enforces bash, Python, Go policy per SCRIPTS-LANGUAGE-POLICY.md—no ad-hoc Node deploy scripts in scripts/. Solution-registry (warn): integration catalog entries reference live manifest ids.
JSON Schema (error in strict, warn locally): packages/contracts/schemas/ validated against manifests, catalog, and registry—the json-schema-ops-validate-contracts article explains the shared contract spine. Json-format (warn): canonical two-space indent on contract JSON. Tunnel (warn): local dev expects SSH tunnel to platform bus health unless skipped. ops/.env.local (warn): reminds operators OPS_SECRET and related local secrets exist before authenticated bus calls.
Integration map at boot
setup-local.sh invokes startup-check after tunnel and env hints. npm predev in the Ops package runs the same script so every dev server start refreshes status. Platform bus main.go logs startup parity and config warnings to stderr before binding :3100—agents and operators see WARN lines in docker logs without opening the UI.
Results flow to three surfaces: data/ops-startup-status.json for SetupPanel rendering, stderr WARN logs for terminal and container visibility, and strict CI exit codes for GitHub Actions. The solution-manifest-config-spine guide explains why manifest errors are severity error—not warn—because every downstream connector action assumes that file is truth.
Ops console SetupPanel
Ops Home SetupPanel reads ops-startup-status.json on load. Warnings appear next to tunnel status, GitHub connector hints, and deploy shortcuts. Operators fix manifest typos or start the bus tunnel before debugging Integration Inspector empty states caused by auth failure rather than config drift.
Additional npm scripts support focused validation: npm run validate:json-schema and npm run format:json-contracts:check in the ops package. These align with startup-check schema subset without running the full twenty-two gate suite.
Platform bus boot validation
Go platform bus embeds JSON schemas at build time—same files ops-validate CLI checks. On startup the bus compares registered routes against expected catalog entries and logs parity gaps. This mirrors frozen-http-contracts-strangler-migration discipline: HTTP paths stay stable while implementation moved Node to Go.
Bus startup warnings do not block ListenAndServe in local profiles; production overlays should treat repeated parity warnings as deploy blockers alongside M17 security gates. The platform-bus-go-migration-shipped story documents why bus correctness matters for CRM-orchestrated outreach.
Scripts and deploy hooks
SA-4 extends awareness to deploy hooks: optional startup-check --strict before Fabric VPS deploy tasks. Scripts that violate language policy surface at boot rather than mid-deploy on dardev-vps. Deployed-realities-explained applies—local drift that never runs validators becomes production surprise.
When adding a new solution manifest, run startup-check immediately after edit. Fix connector registry entries before pushing—strict CI will fail on the same errors, but local WARN feedback saves a PR cycle.
Relationship to full CI
- Boot: startup-check subset, warn-heavy, under ten seconds typical
- PR: validate-all twenty-two gates including maturity M16–M22 where applicable
- Release: strict startup-check plus security and Swarm gates per runbook
- Runtime: bus stderr warnings on parity; Ops SetupPanel reads latest JSON status
Does startup-check replace validate-all?
No. It is a fast subset at boot. Full CI remains ops-validate.sh validate-all for merge and release gates.
Why is tunnel check warn-only?
Developers often start Ops before SSH tunnel to dardev-vps bus. WARN reminds them; --skip-tunnel avoids false positives when working offline on UI-only changes.
What fails --strict locally?
Manifest and connector errors always fail. JSON Schema errors fail in strict mode. Warn-level checks like bus-parity still log but may not fail unless promoted in a future gate.
Where is startup status stored?
data/ops-startup-status.json in repo root, regenerated each startup-check run. Ops SetupPanel consumes it; commit is optional—file is local dev signal.
How does this relate to Ops maturity M17?
M17 hardens production auth. Startup awareness catches contract drift before code reaches production—complementary, not duplicate.
