# Configuration Hardening Audit

This audit records the current repository-configuration authority model for
`sow-toolkit`.

## Authority Rules

- Human-authored root repository configuration is YAML: `nwn-tool.yaml`, then
  `nwn-tool.yml`.
- `nwn-tool.json` is legacy compatibility only. It remains readable during the
  migration window and is reported as deprecated provenance.
- Generated and machine-readable artifacts remain JSON. This includes HAK
  manifests, canonical GFF JSON, topdata datasets, autogen manifests, caches,
  wiki state, deploy manifests, and credits inventories.
- Toolkit defaults are centralized in `internal/project/effective.go` and are
  visible through `sow-toolkit config effective`.
- Environment variables are treated as runtime overrides and are listed by
  `sow-toolkit config sources` and `config effective`. Sensitive values are
  masked.

## Implemented Schema Expansion

- `paths.cache`, `paths.tools`
- `outputs.module_archive`, `outputs.hak_manifest`, `outputs.hak_archive`
- `build.keep_existing_haks`
- `inventory.source_extensions`, `inventory.asset_extensions`,
  `inventory.source_json_pattern`
- `validation.profile`, `validation.builtin_script_prefixes`, and
  `validation.required_fields`
- `scripts.source_dir`, `scripts.cache`, `scripts.compiler`
- `extract.layout`, `extract.hak_discovery`, `extract.cleanup_stale`
- `topdata.compiled_2da_dir`, `topdata.compiled_tlk`, package names, and wiki
  output/deploy defaults
- `autogen.cache.root`, `autogen.cache.max_age`,
  `autogen.cache.refresh_env`, and release-source env names

## Remaining Engine Invariants

These are intentionally still implemented as toolkit behavior rather than
repository-specific YAML:

- Canonical GFF JSON shape.
- ERF/MOD/HAK binary serialization.
- Supported autogen algorithms: `parts_rows`, `head_visualeffects`,
  `trailing_numeric_suffix`, `model_stem`, and `first_path_segment`.
- Native topdata dataset internals and generated JSON dataset formats.
- NWN validator resource-reference checks. These are candidates for future
  validation profiles, but are not repository-specific defaults.

## Migration Checklist

For each consumer repository:

1. Confirm root config is `nwn-tool.yaml` or `nwn-tool.yml`.
2. Remove root `nwn-tool.json` unless it is a deliberate test fixture.
3. Run `sow-toolkit config effective --json` and record generated output,
   cache paths, HAK manifest paths, topdata package names, script compiler
   resolution policy, and active overrides.
4. Move wrapper-provided environment behavior into YAML where it is stable
   repository policy.
5. Keep credentials and one-off CI values as runtime overrides.
6. Run build/validate workflows and compare generated JSON artifacts.

## Follow-Up Tickets

- Remove legacy root JSON loading after all active repositories migrate.
- Add validation-profile schema if repositories need to vary validator rules.
- Complete the separate music dataset refactor described in
  `MUSIC_REFACTOR_CONTRACT.md`.
- Add static linting for new repository-specific literals in command and
  pipeline code.