claude: fold in old sow-tools

2026-06-13 09:49:29 +02:00
parent d4a435883b
commit 56c67132f3
112 changed files with 70812 additions and 74 deletions
@@ -0,0 +1,82 @@
+# `masterfeats` Canonical Contract
+
+## Status Snapshot
+
+Current state as of 2026-05-13:
+
+- Implemented as a first-class native dataset.
+- The repository contains `topdata/data/masterfeats/`, migration/import support,
+  validator checks, and native output coverage for `masterfeats.2da`.
+- Remaining work is only downstream adoption and regression maintenance as other
+  native datasets continue to consume `masterfeats` more heavily.
+
+`masterfeats` is a stable native canonical family consumed directly by `feat`
+generation, class-feat expansion, and inheritance/ref resolution.
+
+Current canonical scope:
+
+- dataset root: `topdata/data/masterfeats/`
+- required files:
+  - `base.json`
+  - `lock.json`
+- generated output:
+  - `masterfeats.2da`
+
+## `base.json`
+
+Canonical shape:
+
+```json
+{
+  "output": "masterfeats.2da",
+  "columns": ["LABEL", "STRREF", "DESCRIPTION", "..."],
+  "rows": [
+    {
+      "id": 0,
+      "key": "masterfeats:weaponfocus",
+      "LABEL": "WeaponFocus",
+      "STRREF": "6490",
+      "DESCRIPTION": "436"
+    }
+  ]
+}
+```
+
+Rules:
+
+- `output` may be omitted; native dataset discovery deterministically derives
+  `masterfeats.2da` from `topdata/data/masterfeats/base.json`
+- if `output` is present, it must be exactly `masterfeats.2da`
+- `columns` must include `LABEL`, `STRREF`, and `DESCRIPTION`
+- every canonical row must have a non-empty `key`
+- row keys must start with `masterfeats:`
+- inline TLK payloads are allowed in `STRREF` and `DESCRIPTION`
+- numeric/text references are both allowed where the native TLK compiler already supports them
+
+## `lock.json`
+
+Canonical shape:
+
+```json
+{
+  "masterfeats:weaponfocus": 0
+}
+```
+
+Rules:
+
+- every key must start with `masterfeats:`
+- every value must be numeric
+- the lockfile remains the canonical stable id source for authored keys
+
+## Module contributions
+
+This family continues to support the shared canonical module shapes already used by native
+datasets:
+
+- `columns`
+- `entries`
+- `overrides`
+
+Those shapes are validated generically in `topdata.go`; this contract only adds the
+family-specific guarantees for `masterfeats`.