In development

Development setup

The repository developer workflow, compiler, guarded build and verification commands.

Status: documentation preparation under ADR-010 W15. Local prototype only. Shell is zsh. Node tooling, when used, is pnpm.

Owned layout#

Path	Role
`src/`	First-party prototype (Zig 0.16.0)
`tests/prototype/`	Domain/service tests
`scripts/`	Probes, `build_guard.py`, `verify.py`
`docs/prototype/`	Operator/developer documentation
`website/`	Public site sources (separate Go module)
`.local/`	Disposable evidence; never publish

Do not export PROJECT-INTERNAL/, credentials, profiles or NEXT-GEN.md into public docs or the website catalog.

Compiler and dependencies#

Pin: Zig 0.16.0 via scripts/zig.sh.
Compiler/stdlib upgrade requires explicit Eris authorization (ZIG-UPGRADES).
Pins and licenses: DEPENDENCIES.md. Offline rebuild needs a populated dependency cache; that is distinct from offline runtime.

Build (G12)#

One guarded build across worktrees; Zig -j1; ≤2 GiB sampled RSS; ≥25% headroom:

python3 scripts/build_guard.py -- zsh scripts/zig.sh build -j1 -Doptimize=ReleaseSafe

Package (destination must not exist):

python3 scripts/build_guard.py -- zsh scripts/zig.sh build package-prototype -j1 -Doptimize=ReleaseSafe -Dpackage-output=/absolute/path/to/new-rural-bundle

Verification#

Command	Scope
`just validate`	Registry/plan/ownership contracts
`just verify policy`	Metadata/policy without full runtime
`just verify`	Full integration (includes runners policy allows)
`python3 scripts/verify.py --profile functional`	ADR-010 lane: no performance runners

Functional lane retains correctness, recovery and security checks. Do not run benchmark/load/soak/adoption suites in that lane.

Useful probes (disposable profiles; no token stdout):

python3 scripts/check_local_service.py
python3 scripts/check_mcp_service.py --binary zig-out/bin/rural
python3 scripts/check_cli_cookbook.py --binary zig-out/bin/rural
python3 scripts/check_cli_cookbook.py --package-bundle /absolute/path/to/bundle

Cancellation and ownership#

Explicit owners for allocations/locks; release on all paths (memory safety).
Service SIGTERM cancels and joins workers before close.
Launcher reaps owned children; do not kill by port/name heuristics in docs examples.

Contribution / review#

File ownership: one owner per file; registry is authoritative.
Independent review before merge; G7 change evidence with pre-edit baseline.
Git: Eris-Margeta author/committer; feat//fix//chore//docs/ branches; no AI attribution; no force-push (DELIVERY).

Recovery troubleshooting#

Symptom	Direction
`stale_session` / unauthorized after restart	Fresh `serve`; old token invalid
`conflict` on mutation	Refresh `expected_head` / revision; do not invent new request id for unknown outcome
`idempotency_conflict`	Same id, different body — keep original identity or new id deliberately
`checkpoint_dependent_backup_unsupported`	Compacted store; journal-only backup refused (W05)
MCP fails after service restart	Restart `rural mcp`; plans are process-local
Unknown outcome after timeout	Retry exact request identity; inspect receipt

Operator recipes: service-cli.md, RUNBOOK.md. Capabilities map: CAPABILITIES.md.