Add hardcore action family metadata

docs/prompt-architecture-improvement-plan.md

@@ -107,6 +107,9 @@ Already isolated:
 - shared hardcore environment-anchor cleanup lives in
   `hardcore_text_cleanup.py` and normalizes malformed pool joins before metadata
   reaches formatter routes.
+- shared hardcore action metadata lives in `hardcore_action_metadata.py`; custom
+  rows now emit `action_family`, `position_family`, `position_key`, and
+  `position_keys` so formatter routing and debugging do less keyword guessing.
 
 ### Pair / Adapter Layer
 
@@ -148,6 +151,8 @@ Already isolated:
 - `krea_action_context.py` owns shared action-family predicates, axis context
   text, climax detection, and detail-density normalization used by action and
   POV formatter routes.
+- `hardcore_action_metadata.py` owns shared action-family constants,
+  normalization, and inference used by the builder and Krea formatter route.
 - `krea_pov.py` owns POV labels, POV label filtering, and POV camera/composition
   support text.
 - `krea_detail.py` owns generic detail-clause splitting, deduping, joining, and
@@ -166,8 +171,8 @@ Already isolated:
 
 Improve later:
 
-- add metadata fields such as `action_family` / `position_family` to reduce
-  keyword guessing in hardcore formatter dispatch;
+- extend SDXL and caption routes to optionally consume `action_family` /
+  `position_family` when ordering tags or caption clauses;
 - add route-level smoke fixtures for representative metadata rows;
 
 ### SDXL Formatter Path
@@ -346,8 +351,8 @@ Medium-term:
 
 ## Recommended Next Passes
 
-1. Add metadata fields such as `action_family` / `position_family` to reduce
-   keyword guessing in hardcore filters and formatter dispatch.
+1. Extend SDXL and caption routes to optionally consume `action_family` /
+   `position_family` when ordering tags or caption clauses.
 2. Split `__init__.py` node classes by family after behavior is covered by smoke
    checks.
 3. Add route-level smoke fixtures for representative Krea/SDXL/caption metadata

docs/prompt-pool-routing-map.md

@@ -397,6 +397,9 @@ plain prompt text. When debugging, inspect these fields before editing pools.
 | `content_seed_axis` | `_build_custom_row` | Debug | Shows whether the item/action was driven by `content` or `pose`. Critical for hardcore pose categories. |
 | `item` | `_compose_item` or Insta override | Krea/SDXL/Naturalizer | Clothing item, category item, or sexual scene/action text. |
 | `item_axis_values` | `_compose_item` | Krea hardcore rewrite, SDXL tags | Filled template axes such as position/action/detail values. |
+| `action_family` | `hardcore_action_metadata.source_hardcore_action_family` | Krea hardcore rewrite, debug | Source-aware formatter semantic family such as `foreplay`, `outercourse`, `oral`, `penetration`, `toy_double`, or `climax`. |
+| `position_family` | `_hardcore_source_position_family` | Debug/filtering | Source/UI hardcore family selected by subcategory, such as `manual`, `interaction`, `oral`, `anal`, or `climax`. |
+| `position_key`, `position_keys` | `_hardcore_position_keys` | Debug/future filters | Concrete position tokens inferred from axes and role text, such as `kneeling`, `doggy`, `boobjob`, or `open_thighs`. |
 | `custom_item`, `item_label` | Category/pair route | Formatters and debug | Label/name for item route. |
 | `role_graph` | `_role_graph`, POV adapter | Krea/Naturalizer | Choreography/action relationship text after POV adaptation. |
 | `source_role_graph` | `_role_graph` before POV rewrite | Krea hardcore rewrite | Raw action graph used to infer position and contact. |
@@ -564,6 +567,7 @@ Key Krea2 ownership:
 
 - Cast descriptor naturalization: `krea_cast.cast_prose`,
   `krea_cast.natural_label_text`.
+- Shared action-family metadata: `hardcore_action_metadata.py`.
 - Action context and family predicates: `krea_action_context.py`.
 - Non-POV pose anchors and arrangements: `krea_action_positions.py`.
 - Non-climax item/detail cleanup: `krea_action_details.py`.
@@ -751,13 +755,15 @@ Use these traces to narrow a problem in one pass.
 ### Hardcore action keeps selecting the same family
 
 1. Check metadata `main_category`, `subcategory`, `content_seed_axis`,
-   `hardcore_position_config`, `item`, `role_graph`, and `item_axis_values`.
+   `action_family`, `position_family`, `position_key`, `hardcore_position_config`,
+   `item`, `role_graph`, and `item_axis_values`.
 2. If `hardcore_position_config` disabled most families, the repeated action may
    be the only compatible pool left.
 3. Inspect `categories/sexual_poses.json` for the selected subcategory,
    `item_templates`, `axes`, and `weight`.
 4. If raw `item` differs but Krea output looks identical, inspect
-   `krea_action_context.py` family predicates first, then
+   `hardcore_action_metadata.py` action-family metadata first, then
+   `krea_action_context.py` family predicates,
    `krea_action_positions.py` pose anchors/arrangements,
    `krea_action_details.py` item/detail cleanup, `krea_action_climax.py`
    climax cleanup, `krea_action_dispatch.py` family routing, and