Tools

Governance directives

Edit source

Governance directives

Centraid uses governance-kit to enforce repository rules at commit time and in CI. Most directives are about repo hygiene (commits, receipts, secrets, file size); one is specific to app authoring.

query-handlers-read-only

The one app-author-facing directive.

Rule. A file at */queries/*.js must not contain stmt.run() or db.exec(). Writes from query handlers must move to actions/*.js.

Why it exists. The runtime's handler-runner skips SQLite session tracking on the read path for performance. Writes from a query handler succeed silently — but they're invisible to the change bus at /centraid/<id>/_changes. Subscribers go stale with no error fired anywhere. The directive is a guardrail against this exact silent failure.

Enforced by.

Code
.governance/packs/srikanth235/centraid/directives/query-handlers-read-only/check.sh

Runs in the pre-commit hook (via .githooks/pre-commit) and re-runs in CI on every PR.

Waiver. Per-line // governance: allow-query-handlers-read-only <reason> for the rare opt-in case (e.g. lazy view materialization on first access). The waiver is visible in git blame and searchable — there's no silent way around it.

js
// queries/lazy-view.js // governance: allow-query-handlers-read-only first-access materializationawait db.prepare(`CREATE VIEW IF NOT EXISTS …`).run(); return await db.prepare('SELECT * FROM view_name').all();

Repo-wide directives that matter for app authors

Several governance-kit directives are not Centraid-specific but apply to anyone contributing to the repo (and so apply to app code that lands in packages/app-templates/ or apps/desktop/):

Directive Summary Waiver
repo-hygiene No merge markers, no build artifacts, no debug prints in non-test source, no source file > 500 lines Line waiver // governance: allow-repo-hygiene <reason>
secrets-hygiene No plaintext tokens or credentials in tracked files Line waiver # governance: allow-secrets-hygiene <reason>
commit-message-format <type>(scope)?!?: subject (#123) with trailing issue ref Merge/revert commits exempt
no-orphan-todos Every TODO/FIXME references a GitHub issue (e.g. #120) or tracker ticket Line waiver
receipt-per-issue Substantive work touches receipts/issue-&lt;N&gt;-<slug>.md with required sections None — receipts are the system of record
no-broken-internal-doc-links Every relative-path markdown link resolves None

See CONSTITUTION.md for the full text of each directive.

Why directives live in the repo

The constitution's cardinal rule:

Amendments to this constitution must land in the same commit as the change to its enforcing test. No exceptions.

Every directive has an executable check under .governance/. A directive with no enforcing test is a wish, not a rule. The whole layer is .governance/run.sh — that one script is what the pre-commit hook and CI invoke.

Where to go next

Was this useful?