Governance

Governance

Lugas is developed under an explicit governance model. Every capability claim is evidence-gated; architecture changes go through Architecture Decision Records (ADRs) authorized by owner decision records (ODRs).

Rules that bind all work

Non-negotiables (from AGENTS.md):

1. Bun-only through 1.x.
2. Bun's native router remains the request-path router.
3. Public APIs stay small, explicit, object-based, statically searchable.
4. Native Request/Response/Headers/URL/FormData/ReadableStream remain available.
5. No ORM / auth product / OpenAPI / JSX / WebSocket / cloud adapter without an ADR.
6. No dependency on Elysia or Eden.
7. No performance claims without reproducible evidence.
8. Compile-time and runtime facts are distinct systems.
9. Package names, repo creation, license, org, domain, and releases are owner decisions.

Prohibited shortcuts include weakening tests to pass, replacing failing benchmark baselines with easier ones, inventing runtime metadata from TypeScript types, and adding any at public boundaries without proof.

Document trail

Artifact	Location
Architecture decisions (ADRs 0001–0025)	docs/okf/decisions/ — index in index.md
Owner decision records (ODRs)	docs/owner-decisions/
Per-issue evidence reports	docs/reports/issues/ — baseline, outcome, acceptance mapping, exact commands/results, security considerations, known limitations, deferred work
Release gates	docs/reports/gates/
Diagnostic catalog	docs/diagnostics.md — frozen LUGAS_<FAMILY>_<NNN> codes

Verification gates

Every implementation change passes the full gate before merge:

bun run verify   # bun-version + typecheck + test + docs + diff

CI additionally runs the suite on Bun 1.4.0 and 1.4.x across Linux, macOS, and Windows. Diagnostics goldens are regenerated only via the intentional bun run scripts/update-goldens.ts --apply, with the reason recorded in the linked issue's evidence report.

Release posture

Release candidates are attested through a fail-closed pipeline: package rehearsal, quiet-host performance budgets, SBOM + generated-artifact inventory, SHA256SUMS verified in a clean clone, and a two-identity binding (package source commit + attestation commit). Publication is always an explicit owner action — nothing ships to npm without it.

Responsible disclosure

Security issues in Lugas are reported privately to the owner and fixed fail-closed before disclosure. Upstream runtime findings (e.g. the Bun directory-route symlink exposure on macOS/Windows, reported to security@bun.com in September 2026) are handled through coordinated disclosure; Lugas fails closed (rejects affected configurations at startup) until upstream fixes land.