Phase 5: scaffold Crucible (sow-tools) — dispatcher + builder shims, container, PR-first CI, fail-closed (D11, D19).

2026-06-11 20:36:13 +02:00
parent ff264f0d7c
commit 97f8427c4b
154 changed files with 948 additions and 76902 deletions
@@ -1,119 +0,0 @@
-# Generic Family Expansion Contract
-
-## Status Snapshot
-
-Current state as of 2026-05-13:
-
- Implemented and actively used by native feat generation.
- `family_expansion.go`, `native.go`, and `topdata_test.go` cover the current
-  underscore-family interpretation, generated family metadata, and reapplication
-  behavior.
- Remaining work is mostly consumer expansion: use the same primitive in more
-  datasets only when the authored data actually benefits from it.
-
-Topdata now treats underscore expansion as a structural rule:
-
- `parent_child` means `child` is an expansion of `parent`
- underscores are for family structure, not simulated spaces
- existing canonical keys still win when lock or TLK state already established them
-
-This is a global interpretation rule, not a wiki-only convention.
-
-## Identity
-
- `weaponspecialization_club`
-  - parent: `weaponspecialization`
-  - child: `club`
- `gnome_rock`
-  - parent: `gnome`
-  - child: `rock`
- `toughness_10`
-  - parent: `toughness`
-  - child: `10`
-
-Standalone keys without an underscore are treated as a parent identity with no child.
-
-## Generated Family Files
-
-Canonical generated families declare:
-
-```json
-{
-  "family": "weapon_focus",
-  "family_key": "weaponfocus",
-  "template": "masterfeats:weaponfocus",
-  "name_prefix": "Weapon Focus",
-  "label_prefix": "FEAT_WEAPON_FOCUS",
-  "constant_prefix": "FEAT_WEAPON_FOCUS",
-  "legacy_family_keys": ["epic_weapon_focus"],
-  "default_fields": {
-    "DESCRIPTION": {
-      "tlk": {
-        "key": "masterfeats:weaponfocus.description",
-        "text": "..."
-      }
-    },
-    "MINATTACKBONUS": "1",
-    "TOOLSCATEGORIES": "1"
-  },
-  "apply_after_modules": true,
-  "identity_source": "child_source_value",
-  "auto_prereq_fields": {
-    "PREREQFEAT1": "weaponfocus"
-  },
-  "child_source": {
-    "dataset": "baseitems",
-    "column": "WeaponFocusFeat"
-  }
-}
-```
-
-Rules:
-
- `family` is an authored label and is not a hardcoded switch key
- `family_key` is the structural parent identity used in generated child keys
- `template` is optional for the primitive in general, but required by current
-  masterfeat-backed `feat` families
- `name_prefix`, `label_prefix`, and `constant_prefix` define how new child rows are
-  named when they are not already authored
- `template_fields` lists template-backed fields copied from the referenced template row
-  when authored; it is optional if the family owns its shared values directly
- `default_fields` applies authored shared/default values to every generated family row
-  and can be used to move family-wide shared values out of the template row
- `apply_after_modules: true` re-applies the generated family after normal module files,
-  so authored family-shared values remain authoritative even for legacy explicitly
-  authored child rows
- `child_ref_field` binds the generated child row back to the source row key, e.g.
-  `REQSKILL`
- `identity_source: "child_source_value"` tells the builder to reuse IDs/keys from the
-  source column when that column already carries feat identity
- `legacy_family_keys` declares previous generated-family prefixes that should donate
-  existing locked row IDs to the current family when a family is renamed
- `auto_prereq_fields` binds prerequisite fields to other authored families by
-  `family_key`, without code changes
- `allow_existing_only` limits expansion to already-authored child rows when a family is
-  intentionally partial
- `child_source.dataset` identifies the canonical dataset driving expansion
- `child_source.column` is used when expansion is gated by a non-null source field
- `child_source.predicate` is used when expansion depends on a named rule such as
-  accessibility
-
-## Row Metadata
-
-Generated rows can carry:
-
-```json
-{
-  "meta": {
-    "family": {
-      "parent": "weaponfocus",
-      "child": "club",
-      "source": "baseitems:club",
-      "template": "masterfeats:weaponfocus"
-    }
-  }
-}
-```
-
-This metadata is builder-owned and does not affect emitted 2DA columns. It preserves
-family structure for later phases without enabling wiki generation yet.