Phase 5: scaffold Crucible (sow-tools) — dispatcher + builder shims, container, PR-first CI, fail-closed (D11, D19).

2026-06-11 20:36:13 +02:00
commit 0d6eb2aeaa
28 changed files with 987 additions and 0 deletions
@@ -0,0 +1,57 @@
+---
+description: sow-tools / Crucible — the build/conversion/sync toolchain repo.
+alwaysApply: true
+---
+
+# sow-tools / Crucible Agent Guide
+
+This repo owns the **builder logic** for the migration: one Go module
+(`gitea.westgate.pw/ShadowsOverWestgate/sow-tools`) producing the `crucible`
+dispatcher and the `crucible-<name>` binaries (D11). Read
+[`../AGENTS.md`](../AGENTS.md) (migration hub) and
+[`../../KICKOFF_PROMPT.md`](../../KICKOFF_PROMPT.md) first.
+
+## 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`).
+
+## Scaffold rules (Phase 5)
+
+1. **Source is not transplanted.** The migration hard rules forbid copying the
+   `internal/` packages from `gitea/sow-tools` automatically. The operator
+   migrates them at cutover; see [`docs/migration-from-nwn-tool.md`](docs/migration-from-nwn-tool.md).
+2. **Fail closed, never fake.** Unwired builders exit `70`. Do not stub a
+   builder to emit a placeholder artifact.
+3. **Binaries are not committed.** They are CI artifacts / image layers (D19).
+   `/bin/`, `*.exe`, `nwn-tool`, `sow-toolkit` are gitignored.
+4. **No home-dir / `NWN_ROOT` guessing.** Builders take roots explicitly via
+   flag or env. See [`docs/consumer-contract.md`](docs/consumer-contract.md).
+5. **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`](docs/command-surface.md). Adding a builder = a
+   `cmd/crucible-<name>/main.go` shim + a `Registry` entry + a doc row.
+
+## Wiring a builder (operator cutover)
+
+1. Migrate the relevant `internal/` package(s) from `gitea/sow-tools`.
+2. Register a handler and flip the builder off the unwired path in
+   `internal/dispatch`.
+3. Add tests; keep outputs deterministic (same input → same bytes).
+4. `make check` must stay green; `make smoke` is updated to expect a wired exit.
+
+## Commands
+
+```bash
+nix develop && make check   # vet + test + shellcheck + yamllint
+make build                  # cmd/* -> ./bin
+make smoke                  # assert fail-closed contract
+make image                  # crucible:<sha>
+```
+
+## Git
+
+Never commit, branch, or push. Suggest a commit message; let the operator do it.