Family Expansions

internal/topdata/FEAT_GENERATED_FAMILIES_CONTRACT.md

@@ -12,7 +12,6 @@ Canonical authored paths:
 - `topdata/data/feat/generated/greater_weapon_specialization.json`
 - `topdata/data/feat/generated/improved_critical.json`
 - `topdata/data/feat/generated/overwhelming_critical.json`
-- `topdata/data/feat/generated/proficiencies.json`
 - `topdata/data/feat/modules/activecombat/core.json`
 - `topdata/data/feat/modules/activecombat/specialattacks.json`
 - `topdata/data/feat/modules/class/core.json`
@@ -38,6 +37,23 @@ Compact family-expansion shape:
   "family": "skill_focus",
   "family_key": "skillfocus",
   "template": "masterfeats:skillfocus",
+  "name_prefix": "Skill Focus",
+  "label_prefix": "FEAT_SKILL_FOCUS",
+  "constant_prefix": "FEAT_SKILL_FOCUS",
+  "default_fields": {
+    "DESCRIPTION": {
+      "tlk": {
+        "key": "masterfeats:skillfocus.description",
+        "text": "..."
+      }
+    },
+    "CRValue": "0.5",
+    "ReqSkillMinRanks": "1",
+    "TOOLSCATEGORIES": "6"
+  },
+  "apply_after_modules": true,
+  "child_ref_field": "REQSKILL",
+  "allow_existing_only": true,
   "child_source": {
     "dataset": "skills",
     "predicate": "accessible"
@@ -57,6 +73,21 @@ Weapon family shape:
   "family": "weapon_focus",
   "family_key": "weaponfocus",
   "template": "masterfeats:weaponfocus",
+  "name_prefix": "Weapon Focus",
+  "label_prefix": "FEAT_WEAPON_FOCUS",
+  "constant_prefix": "FEAT_WEAPON_FOCUS",
+  "default_fields": {
+    "DESCRIPTION": {
+      "tlk": {
+        "key": "masterfeats:weaponfocus.description",
+        "text": "..."
+      }
+    },
+    "MINATTACKBONUS": "1",
+    "TOOLSCATEGORIES": "1"
+  },
+  "apply_after_modules": true,
+  "identity_source": "child_source_value",
   "child_source": {
     "dataset": "baseitems",
     "column": "WeaponFocusFeat"
@@ -71,23 +102,20 @@ Weapon family shape:
 
 Rules:
 
-- compact generated families are:
-  - `skill_focus`
-  - `greater_skill_focus`
-  - `weapon_focus`
-  - `weapon_specialization`
-  - `greater_weapon_focus`
-  - `greater_weapon_specialization`
-  - `improved_critical`
-  - `overwhelming_critical`
-  - `proficiencies`
-- compact families must declare `template`
-- compact families must also declare:
-  - `family_key`
-  - `child_source.dataset`
-- weapon families must also declare `child_source.column`
-- skill families use `child_source.predicate: "accessible"` to mean
-  `HideFromLevelUp != 1`
+- any generated feat file with family-expansion fields is treated as an authored
+  family-expansion definition
+- `family` is descriptive only; the builder does not hardcode family names
+- family behavior is driven by authored fields such as `template_fields`,
+  `default_fields`, `apply_after_modules`, `identity_source`, `child_ref_field`,
+  and `auto_prereq_fields`
+- `default_fields` is a family-wide shared layer; it applies to existing and newly
+  generated child rows before per-child overrides are merged
+- `apply_after_modules: true` makes the generated family the final authoritative shared
+  layer for legacy explicitly authored child rows, so shared baselines can live in the
+  generated family file instead of `masterfeats` overrides
+- family-expansion files must declare `template`, `family_key`, and `child_source.dataset`
+- `child_source.column` is used when expansion is gated by a non-null source field
+- `child_source.predicate: "accessible"` currently means `HideFromLevelUp != 1`
 - compact `overrides` are keyed by source dataset key:
   - `skills:*` for skill families
   - `baseitems:*` for weapon families
@@ -95,8 +123,6 @@ Rules:
   before wiki generation exists
 - emitted feat keys must prefer existing canonical lock/TLK identities over newly
   derived child spellings
-- `proficiencies.json` is limited to the real masterfeat-backed `weaponproficiencycommoner_*`
-  family
 - manual and irregular feat content continues to live under `feat/modules/`
 - generated families and module-authored feats are merged into the same final `feat.2da`
   pipeline and share inheritance, override, TLK, and family-metadata behavior