Schema for the post-convergence theme + subtheme labeling pass

Used by ai_label_theme_set() in a single AI call after multi-pass clustering has converged. The AI sees the FULL converged tree (themes -> subthemes -> codes) and assigns researcher-facing names + descriptions to every node.

Usage

.theme_labeling_schema()

Details

Design contract (binding under C-tenet 5):

(a) Labeling happens AFTER structural decisions. The AI cannot influence which codes belong to which theme during this call – the structure is fixed.

(b) The AI sees ALL themes + ALL subthemes + ALL codes in one prompt, so cross-theme name distinctness is enforceable (the AI is explicitly instructed not to use the same or near-duplicate names for two themes).

(c) The response shape mirrors the structural skeleton: themes array, each theme has subthemes array. The orchestrator binds names back to the skeleton positionally via theme_index and subtheme_index.

(d) The AI returns the same number of themes as the skeleton has, and the same number of subthemes per theme. Orchestrator post-validates this and re-prompts on mismatch.

  {
    "themes": [
      {
        "theme_index": int,             // 1-based, must match skeleton
        "name": str,                    // 3-12 words, substantive noun phrase
        "description": str,             // 1-2 sentences in researcher voice
        "subthemes": [
          { "subtheme_index": int, "name": str, "description": str }, ...
        ]
      }, ...
    ]
  }