Research spike: WolvenKit as a QuickBMS/wcc_lite replacement

[TheValiantOne]

Summary

This is Wave 0 / Unit 3 of the ongoing re-architecture effort: a research spike, not an implementation change. Deliverable is a single new doc, docs/decisions/bundle-format-replacement-spike.md.

• Investigated whether WolvenKit.Modkit (NuGet, GPL-3.0) could replace QuickBMS (.bundle unpack) + wcc_lite (.bundle repack + metadata.store regeneration), both currently invoked as external processes with no license file in their local distribution.
• Finding 1: WolvenKit.Modkit targets Cyberpunk 2077 / REDengine 4 (.archive format) — the wrong game/format entirely. The actual Witcher-3-targeted tool is a separate repo, WolvenKit/WolvenKit-7.
• Finding 2: WolvenKit-7 does contain a pure-C# .bundle/metadata.store reader (WolvenKit.Bundles), but it's not published as a NuGet package, targets net481, and is coupled to WinForms/WCF — not a drop-in dependency.
• Finding 3 (the real discriminator): WolvenKit-7's metadata.store writer is unimplemented — confirmed both via its own tracking issue (WolvenKit/WolvenKit#33, "Metadata.store parser," opened 2017, closed 2022 with the - [ ] Writer checklist item never checked) and by reading the current source: Metadata_Store.Write is a literal //TODO: Code this when everything is figured out. stub, and every serializer throws NotImplementedException(). WolvenKit-7's own GUI pack pipeline still shells out to the same closed-source wcc.exe WSM already depends on.
• License analysis of the three options the unit asked for (relicense WSM to link WolvenKit-7 as a library / shell out to a WolvenKit CLI as a separate process / keep QuickBMS+wcc_lite as-is) — recommends the third: staying parked, since neither of the other two options unlocks any actual new capability given the writer gap.

No code changes — doc-only. Per the unit's scope, no implementation was attempted even though parts of the read path looked feasible; that's explicitly out of scope here.

How this was researched/verified

• Read WitcherScriptMerger/Tools/QuickBms.cs, WitcherScriptMerger/Tools/WccLite.cs, CLAUDE.md's "External tool dependencies," and the root LICENSE directly.
• Read witcher3.bms (the QuickBMS plugin WSM's configured tooling ships) directly for .bundle format comments — reachable in this environment; the doc says so explicitly and doesn't block on that reachability for future readers.
• Fetched WolvenKit.Modkit's and WolvenKit.RED3.CR2W's NuGet Gallery pages for descriptions/dependencies/license/owner.
• Used gh api/gh issue view to pull real repo metadata (license, push dates, star/issue counts) for WolvenKit/WolvenKit-7, the full body/checklist/comments of issue #33, and the literal current source of WolvenKit.Bundles/Metadata_Store.cs, Bundle.cs, WolvenKit.Bundles.csproj, WolvenKit.Common/Model/Wcc/wcc_task.cs, WolvenKit.App/Model/WccHelper.cs, and WolvenKit.Console/Options.cs — pinned at commit c3c1c2028177de37c97a2706412b499a5c04cbf4 (noted in the doc's Sources section for future re-verification).
• Grepped this repo for any GPL "or later" grant outside LICENSE (none found) to support the license-compatibility analysis.
• Ran the code-review skill against the diff; it fact-checked citations against live sources and flagged two real issues (a self-contradictory description of the license grep methodology, and an incomplete framing of option (a) that didn't account for WSM being a fork with pre-fork copyright — relicensing may need consent beyond current maintainers). Both fixed before this PR.
• dotnet build WitcherScriptMerger.sln succeeds (doc-only change, included as a sanity check per the unit's process).

Full citation list with URLs is in the doc's own "Sources consulted" section.

AI assistance disclosure

This PR was researched and written by a Claude Code agent (Sonnet 5), per this repo's CONTRIBUTING.md AI-assisted-development policy. All factual claims are attributed to a URL or a specific file/commit read directly rather than asserted from model knowledge.

Test plan

• dotnet build WitcherScriptMerger.sln succeeds
• Doc re-read for internal consistency (recommendation follows from evidence)
• Every factual claim about WolvenKit attributed to a source (URL, file path, or gh api/gh issue view call)
• No machine-specific absolute paths (e.g. G:\SteamLibrary\...) left in the diff
• code-review skill run against the diff; findings addressed

https://claude.ai/code/session_01GXAuGMLB44T5Zv5o5ZzKah