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,76 @@
+# Class Feat Global Injection Contract
+
+## Status Snapshot
+
+Current state as of 2026-06-05:
+
+- Preferred class feat injection policy is authored in
+  `topdata/data/classes/feats/global.json`.
+- `global.json` rows flow through the ordinary class feat expansion pipeline,
+  including successor expansion, masterfeat expansion, class-skill filtering,
+  reference resolution, deduplication, and final 2DA emission.
+- Legacy `topdata.class_feat_injections` YAML still loads only as a
+  compatibility path when no applicable class feat `global.json` exists.
+- Toolkit hardcoded defaults are compatibility-only and must not be the normal
+  source of project policy.
+
+## Objective
+
+Native class feat generation must produce deterministic, legacy-equivalent
+effective output while keeping project policy in topdata authoring files.
+
+## Requirements
+
+- For each class skill, inject the configured skill-focus masterfeat rows from
+  `classes/feats/global.json` using `FeatIndex.filter = "classskills"`.
+- Inject `feat:literate` only when the class table does not already include
+  `feat:illiterate`.
+- Inject the shared combat/menu feat rows declared in the manifest unless a
+  class already authors the equivalent `FeatIndex`.
+- Explicit class feat rows take precedence over injected rows.
+- Injections must be deterministic for identical inputs.
+
+## Manifest Shape
+
+```json
+{
+  "position": "prepend",
+  "injections": [
+    {
+      "row": {
+        "FeatIndex": { "id": "feat:literate" },
+        "GrantedOnLevel": 1,
+        "List": 3,
+        "OnMenu": 0
+      },
+      "unless_present": [
+        { "field": "FeatIndex", "id": "feat:illiterate" }
+      ]
+    },
+    {
+      "row": {
+        "FeatIndex": {
+          "id": "masterfeats:skill_focus",
+          "filter": "classskills"
+        },
+        "GrantedOnLevel": -1,
+        "List": 1,
+        "OnMenu": 0
+      }
+    }
+  ]
+}
+```
+
+`position` defaults to `append`. The module uses `prepend` for class feat
+injections to keep generated policy rows before per-class authored rows.
+
+## Acceptance Criteria
+
+- Class feat output contains the same effective shared feats as the prior YAML
+  policy.
+- Literacy injection is skipped for illiterate classes.
+- Skill-focus masterfeat rows expand only for class skills.
+- YAML compatibility continues to work for consumers that have not migrated.
+- A project with `classes/feats/global.json` does not also receive YAML or
+  hardcoded default class feat injections.