sow-tools/AGENTS.md

description, alwaysApply

description	alwaysApply
sow-tools / Crucible — the build/conversion/sync toolchain repo.	true

sow-tools / Crucible Agent Guide

This repo owns the builder logic: one Go module (git.westgate.pw/ShadowsOverWestgate/sow-tools) producing the crucible dispatcher and the crucible-<name> binaries.

What this repo owns / does not own

Owns: build/extract/validate/compare pipeline, ERF/HAK packing, topdata 2da/tlk compilation, wiki rendering/deploy, depot blob verify, music conversion, changelog. Does not own authored game content (that is sow-module / sow-topdata / sow-assets-manifest) or any production deploy authority (that is sow-platform).

Rules

1. Fail closed, never fake. A builder with no migrated logic yet (depot) exits 70. Do not stub a builder to emit a placeholder artifact.
2. Binaries are not committed. They are CI artifacts / image layers. /bin/, *.exe, nwn-tool, sow-toolkit are gitignored.
3. The registry is the command surface. internal/dispatch.Registry is the single source of truth; keep it in sync with cmd/ and docs/command-surface.md. Adding a builder = a cmd/crucible-<name>/main.go shim + a Registry entry + a doc row.

Wiring a builder

1. Ensure the relevant internal/ package(s) cover the work.
2. Add tests; keep outputs deterministic (same input → same bytes).
3. make check must stay green; update make smoke to expect the wired exit.

Commands

nix develop && make check   # vet + test + shellcheck + yamllint
make build                  # cmd/* -> ./bin
make smoke                  # assert fail-closed contract
make image                  # crucible:<sha>

Tests

Tests must survive harmless changes to constants, defaults, wording, ordering, fixture data, and internal implementation details. A test that fails merely because a basic value changed is usually a bad test. Only assert exact values when the value is part of a documented public contract, external protocol, compatibility requirement, security rule, migration, or business rule.