Null key overrides generate null rows

SCRIPT_WRAPPER_CONTRACT.md

@@ -13,66 +13,51 @@ Current state as of 2026-05-13:
 - The previously stale JSON-config assumption shown in this contract is no
   longer current; active repos use `nwn-tool.yaml`.
 
-## Active Scope
+## Scope Status
 
-This contract is still active, but the priority has changed.
+This contract is complete for active root wrappers as of 2026-05-13.
 
-The old priority was:
+Completed:
 
-- make `$@` / `@args` forwarding work
+- root `.sh` wrappers are thin `cd` plus `scripts/run-nwn-tool.sh` launchers
-
+- root `.ps1` wrappers are thin `scripts/run-nwn-tool.ps1` launchers
-The current priority is:
+- all active root wrappers forward arbitrary arguments transparently
-
+- shell and PowerShell wrapper regression coverage includes every active root
-- remove wrapper-side business logic that still duplicates toolkit behavior
+  wrapper in `module/` and `assets/`
-- keep wrappers thin across shell, PowerShell, and release-entrypoint paths
+- stale documentation references to unsupported root wrappers were removed
-- align wrapper logs and error handling with the current logging contract
-- finish wrapper/tooling parity before moving deeper into wiki deployment
 
 ## Current Findings
 
-The main active wrapper gap is no longer argument forwarding or root-wrapper
+No active root-wrapper thinning work remains.
-thickness. The root wrappers are already thin `cd` plus `run-nwn-tool` launchers.
+
-The remaining wrapper-adjacent thickness is release orchestration:
+The scripts below are intentionally not root wrappers:
 
 - `module/scripts/release-all.sh` and `assets/scripts/release-haks.sh` both
-  parse effective config themselves and still own substantial orchestration that
+  parse effective config and own release publishing orchestration.
-  is not just "launch the toolkit".
 - `scripts/run-nwn-tool.*` still own tool installation/update bootstrap. This is
   shared repo plumbing, not build business logic.
 
-That means the wrapper contract should now optimize for:
+These scripts remain acceptable under this wrapper contract because they are
+release/bootstrap plumbing, not user-facing build/extract wrappers. Future
+release automation cleanup should happen under release or logging contracts, not
+by adding logic to root wrappers.
 
-- a single source of truth for preflight behavior
+## Maintenance Rules
-- preserving thin root wrappers
-- shared repo plumbing only where toolkit ownership is not appropriate
-- no duplicated config decoding logic between `.sh` and `.ps1`
 
-## Deferred Scope
+1. Keep paired `.sh` and `.ps1` root wrappers thin; do not add new wrappers
-
-Defer unrelated wrapper-adjacent work for now:
-
-- model-compilation wrapper concerns
-- release-announcement publication scripting
-- broader asset-processing script consolidation outside wrapper ownership
-
-## Immediate Plan
-
-1. Audit every wrapper that does more than `cd` plus `exec`.
-2. Classify wrapper logic into:
-   - toolkit-owned behavior
-   - shared repo plumbing
-   - release-only orchestration
-3. Keep paired `.sh` and `.ps1` root wrappers thin; do not add new wrappers
    unless a command is intentionally promoted to a user-facing entrypoint.
-4. Expand regression coverage from spot checks to all active root wrappers.
+2. Root wrappers must not parse config, inspect source trees, preflight build
-5. Continue release-entrypoint review separately:
+   products, or duplicate toolkit command decisions.
-   - wrapper-side preflight behavior
+3. `scripts/run-nwn-tool.*` may keep tool install/update bootstrap, but must not
-   - stderr/stdout separation for JSON-producing subcommands
+   perform command-specific build logic.
-   - shell/PowerShell parity for any remaining unavoidable wrapper logic
+4. Release-entrypoint orchestration belongs in release contracts; do not treat it
+   as a reason to thicken root wrappers.
+5. If a root wrapper is added or removed, update README command lists and wrapper
+   contract tests in the same change.
 
-# Problem
+# Historical Problem
 
-The current `.sh` and `.ps1` wrapper scripts do not properly forward arbitrary CLI arguments to the underlying toolkit commands.
+Earlier `.sh` and `.ps1` wrapper scripts did not properly forward arbitrary CLI arguments to the underlying toolkit commands.
 
 Example:
 
@@ -84,7 +69,7 @@ Example:
 - `--force`
 - future flags
 
-Many wrappers only support fixed commands or partially forward arguments.
+That passthrough issue is now fixed for active root wrappers.
 
 Additionally, after recent refactors — including:
 
@@ -94,7 +79,7 @@ Additionally, after recent refactors — including:
 - command refactors
 - repository abstraction changes
 
-— several wrapper scripts are now outdated and no longer correctly reflect the current toolkit behavior.
+— several wrapper scripts became outdated and no longer correctly reflected toolkit behavior.
 
 Example of a recent error produced:
 
@@ -121,9 +106,9 @@ Traceback (most recent call last):
 FileNotFoundError: [Errno 2] No such file or directory: '${HOME}/Projects/nwnee-shadowsoverwestgate/assets/nwn-tool.json'
 ```
 
-# Goal
+# Completed Goal
 
-Make all wrapper scripts:
+Active root wrapper scripts are now:
 
 - consistent
 - argument-transparent