Configuration

Two TOML files live in .govforge/ at every project root: config.toml (runtime knobs) and policies.toml (the policy registry). A third file, govforge.db, is the SQLite database — not user-editable.

.govforge/config.toml

Project-level configuration. Generated by gf init; safe to commit.

# Local API binding (consumed by `gf api serve` and the CLI).
api_url = "http://127.0.0.1:8787"

# Project metadata. The `name` shows up in the cockpit and audit exports.
[project]
name = "myrepo"
default_branch = "main"

Key	Default	Description
api_url	http://127.0.0.1:8787	Override per-project. CLI hits this URL.
project.name	directory name	Display name in the cockpit + audit exports.
project.default_branch	main	Inferred from Git on gf init if .git/ is present

Resolution order (Viper)

1. Built-in defaults
2. .govforge/config.toml (walked-up from the current working directory)
3. GOVFORGE_* environment variables (GOVFORGE_API_URL, …)
4. CLI flags (--api-url, --config, --json, --no-color)

Later wins. The walk-up means you can run gf from any subdirectory of the project and it'll find the right config.

---

.govforge/policies.toml

The policy registry. Each top-level table names a policy class registered in backend/src/govforge/core/policies/defaults.py or a custom subclass you've registered separately.

[auth_change_requires_review]
enabled = true
severity = "high"
patterns = ["auth", "session", "jwt", "permission", "middleware"]

[secret_pattern_detection]
enabled = true
severity = "critical"
file_patterns = [".env"]
content_patterns = ["AWS_SECRET_ACCESS_KEY", "PRIVATE_KEY", "password=", "api_key="]

[test_required_for_high_risk]
enabled = true
severity = "medium"

[migration_requires_review]
enabled = true
severity = "high"

[large_diff_requires_human_approval]
enabled = true
severity = "medium"
max_lines_changed = 500

Common keys (all policies)

Key	Type	Default
enabled	bool	true
severity	info / low / medium / high / critical	medium

Setting enabled = false keeps the policy in the registry but excludes it from runs. Removing the section entirely also disables it (defaults populate the registry, but only enabled specs are instantiated).

Per-policy keys

auth_change_requires_review

Key	Type	Default
patterns	list[str]	["auth", "session", "jwt", "permission", "middleware"]

Match is case-insensitive substring against every changed file path.

secret_pattern_detection

Key	Type	Default
file_patterns	list[str]	[".env"]
content_patterns	list[str]	["AWS_SECRET_ACCESS_KEY", "PRIVATE_KEY", "password=", "api_key="]

file_patterns match changed paths (case-insensitive). content_patterns match the diff text (case-insensitive substring). Filename matches emit WARNING; content matches emit BLOCKED.

test_required_for_high_risk

No tunables. Triggers only when the decision's risk is high or critical. A diff that touches at least one path matching (^|/)(tests?|__tests__|test_*\.py|*\.test\.[a-z]+) passes; otherwise emits WARNING.

migration_requires_review

No tunables. Path regex (case-insensitive): (^|/)(migrations?|alembic/versions)/.+\.(py|sql)$. Match → BLOCKED.

large_diff_requires_human_approval

Key	Type	Default
max_lines_changed	int	500

(insertions + deletions) > max_lines_changed → BLOCKED.

Custom policies

Adding a policy is one Python class — see policy-authoring.md.

---

Environment variables (full list)

Var	Effect
GOVFORGE_DB	Path or SQLAlchemy URL. Defaults to .govforge/govforge.db.
GOVFORGE_API_URL	Overrides api_url from config.
GOVFORGE_API_HOST	Bind host for gf api serve.
GOVFORGE_API_PORT	Bind port for gf api serve.
GOVFORGE_DATABASE_URL	Backend-side DB URL override (used by make_engine).
NEXT_PUBLIC_GOVFORGE_API	Cockpit UI's API base URL.
NO_COLOR	Disable ANSI styling everywhere.

---

Reset

# Wipe everything for the project (DB included). Re-run gf init after.
rm -rf .govforge/

# Keep the schema, drop the data only:
rm .govforge/govforge.db && gf init --force

gf init --force overwrites config.toml and policies.toml and re-creates the database. Existing decisions / tasks / events are lost. There is no Phase 1 export → re-import path; back up .govforge/govforge.db if it matters.