docs(skill): close xlsx-workbook-template-creator content gaps — canonical READMEs + catalog-aware validator (PR #143)

.claude/skills/xlsx-workbook-template-creator/SKILL.md

@@ -42,10 +42,17 @@ Before scaffolding, answer:
 bash .claude/skills/xlsx-workbook-template-creator/scripts/create-template.sh
 
 # Step 2 — Review + customize the generated config
-#   Read references/decision-tree-single-vs-multi-turn.md FIRST
-#   Then edit src/config/xlsxTemplates/<new-id>.js phase prompts + audit rules
-#   Reference: references/audit-rules-cookbook.md
-#              references/phase-budget-calibration.md
+#   READ FIRST (PR #143 canonical authority):
+#     - super-legal-mcp-refactored/src/config/xlsxTemplates/README.md
+#       (template schema, 3 trigger fields, 12 layouts, XLSX_TEMPLATE_BASE reference,
+#        dispatch priority matrix, extension workflow)
+#     - super-legal-mcp-refactored/prompts/xlsx-templates/README.md
+#       (prose sidecar design, consumption flow, 10 pitfalls, when to create vs reuse)
+#   THEN edit src/config/xlsxTemplates/<new-id>.js + prose sidecars
+#   Skill references for PR-history lessons:
+#     - references/decision-tree-single-vs-multi-turn.md (single vs multi-turn decision)
+#     - references/phase-budget-calibration.md (PR #134 sensitivity isolation)
+#     - references/audit-rules-cookbook.md (canonical XLSX_TEMPLATE_BASE)
 
 # Step 3 — Validate the config against current bridge signature
 python3 .claude/skills/xlsx-workbook-template-creator/scripts/validate-template.py <new-id>
@@ -104,13 +111,26 @@ The post-PR-138 architecture provides automatic observability + persistence via
 
 ## Cross-references
 
+### Canonical READMEs (PR #143 — READ THESE FIRST when customizing a scaffold)
+
+- **Template structure, triggers, layouts, audit primitives**: [`super-legal-mcp-refactored/src/config/xlsxTemplates/README.md`](../../../super-legal-mcp-refactored/src/config/xlsxTemplates/README.md) — schema, 3 trigger fields, 12 layouts, `XLSX_TEMPLATE_BASE` reference, dispatch priority matrix, extension workflow
+- **Prose sidecar design**: [`super-legal-mcp-refactored/prompts/xlsx-templates/README.md`](../../../super-legal-mcp-refactored/prompts/xlsx-templates/README.md) — consumption flow, sidecar types with walkthroughs, 10 pitfalls, when to create vs reuse, multi-turn truncation gotcha
+
+### Skill reference docs (lessons + pitfalls from PR history)
+
 - **PR #134** (sensitivity isolation principle): `references/phase-budget-calibration.md`
 - **PR #135** (envelope schema variants, Option A pivot): `references/envelope-handling-pr135.md`
 - **PR #138** (callerCategory + observability hooks): `references/observability-hooks-pr138.md`
 - **PR #140** (alerts + dashboard auto-apply per template_id): `references/observability-hooks-pr138.md` §"auto-apply matrix"
 - **Pitfalls + post-mortems**: `references/pitfalls-pr134-pr140.md`
 - **Pre-PR checklist**: `references/verification-checklist.md`
 
+### Skill pointer references (point to canonical READMEs above)
+
+- **Triggers field catalog**: `references/triggers-field-catalog.md` → canonical README §3
+- **Sheet layout catalog**: `references/sheet-layout-catalog.md` → canonical README §4
+- **Prose sidecar design**: `references/prose-sidecar-design.md` → canonical prompts README
+
 Related skills:
 - `code-execution-models` — when adding a new code-execution model (not template)
 - `feature-compliance-scaffold` — defensive pre-PR audit (run AFTER scaffolding)

.claude/skills/xlsx-workbook-template-creator/references/decision-tree-single-vs-multi-turn.md

@@ -5,7 +5,7 @@
 | | Single-turn | Multi-turn |
 |---|---|---|
 | Template has `phaseSplit` field? | NO | YES (phase1+phase2+phase3 required; phase4+phase5 optional) |
-| Bridge invocation | `xlsxRenderer/index.js:208` (single `runAnalysis(spec)`) | `xlsxRenderer/multiTurnOrchestrator.js:107` (per-phase) |
+| Bridge invocation | `xlsxRenderer/index.js:210` (single `runAnalysis(spec)`) | `xlsxRenderer/multiTurnOrchestrator.js:107` (per-phase) |
 | `callerCategory` set in gather.js | `xlsx_single_turn` | `xlsx_multi_turn` |
 | Best for | Simple workbooks, ≤ 240s wall time, no specialty audit | Complex workbooks, > 240s, per-phase isolation needed |
 | Existing example | `session-models` (priority 10, fallback) | `full-deal-workbook` (5 phases), `lbo-focused` (4), `valuation-only` (4), `tax-memo-workbook` (4) |
@@ -63,7 +63,7 @@ export default { def };
 ### Single-turn invocation flow
 
 ```
-xlsxRenderer/index.js:208
+xlsxRenderer/index.js:210
   └── composeWorkbookSpec(template, inputs, sessionId)
       └── spec.callerCategory = 'xlsx_single_turn'      ← CRITICAL (PR #138)
       └── spec.constraints.output_format includes 'b64_xlsx' → triggers ENVELOPE_SCHEMA_XLSX

.claude/skills/xlsx-workbook-template-creator/references/prose-sidecar-design.md

@@ -0,0 +1,19 @@
+# Prose Sidecar Design (skill pointer)
+
+**Canonical authority**: [`super-legal-mcp-refactored/prompts/xlsx-templates/README.md`](../../../../super-legal-mcp-refactored/prompts/xlsx-templates/README.md)
+
+The canonical README covers:
+
+- **What sidecars are**: markdown files injected verbatim into bridge task text (NOT Python code, NOT schema specs)
+- **Consumption flow**: `gather.js loadProseSidecars()` → `buildTaskText()` / `buildPhaseTaskText()` with line citations
+- **4 sidecar types** with annotated walkthroughs of existing examples (cover, exec_summary, disclaimer, phase)
+- **Common structural patterns**: Lead → Contents → Usage → Audit (240-337 word range)
+- **10 documented pitfalls** from existing sidecar audit (markdown table conversion, formula references, terminology assumptions, etc.)
+- **When to create new sidecar vs reuse**: always reuse `_disclaimer.md`; always create `<id>-cover.md`; conditionally create `<id>-executive-summary.md`
+- **Multi-turn truncation gotcha**: 1500-char slice in final phase only (per `gather.js buildPhaseTaskText():481`)
+
+The scaffolder creates placeholder sidecar files with TODO content. **Replace TODO content with real prose following the patterns in §3 + §4 of the canonical README.** Existing templates (`full-deal-workbook-cover.md`, `valuation-only-cover.md`, etc.) are the canonical examples.
+
+## Why this skill reference is thin
+
+The canonical doc lives alongside the prose sidecars themselves (`prompts/xlsx-templates/README.md`), so the next engineer browsing existing sidecars sees the design guide in the same `ls` listing. Skill references duplicating content would drift; this pointer keeps the skill as the entry point but defers authority to the colocated README.

.claude/skills/xlsx-workbook-template-creator/references/sheet-layout-catalog.md

@@ -0,0 +1,17 @@
+# Sheet Layout Catalog (skill pointer)
+
+**Canonical authority**: [`super-legal-mcp-refactored/src/config/xlsxTemplates/README.md` §4 — Sheet layouts catalog](../../../../super-legal-mcp-refactored/src/config/xlsxTemplates/README.md#4--sheet-layouts-catalog)
+
+The canonical README enumerates:
+
+- **12 available layouts** in `_layouts.js LAYOUTS`: `cover`, `exec_summary`, `assumptions`, `three_statement`, `dcf`, `comps`, `lbo`, `sensitivity_2d`, `risk_register`, `sources_index`, `model_index`, `auto_per_model`
+- **Per-layout reference**: what each produces, source shape requirements, constraints, which templates use each
+- **3 source shapes** (string file/state key, `{ code_execution: { model_id } }`, `{ aggregate: [...] }`, `{ iterate: 'code_executions' }`)
+- **`auto_per_model` special semantics**: dynamic per-model tabs with max_tabs=20 safety cap (session-models fallback only)
+- **Extension workflow**: how to add a new layout (edit `_layouts.js` + update README + update renderer's openpyxl Python if needed)
+
+When the skill's `validate-template.py` warns "Unknown layout" (CHECK 19), it's saying the layout name isn't listed in §4. Either fix the typo OR extend §4 + `_layouts.js` if intentionally adding one.
+
+## Why this skill reference is thin
+
+The canonical doc lives alongside the templates + layouts it describes (`src/config/xlsxTemplates/README.md`), so the next engineer touching `_layouts.js` sees it in the same `ls` listing. Skill references duplicating content would drift; this pointer keeps the skill as the entry point but defers authority to the colocated README.

.claude/skills/xlsx-workbook-template-creator/references/triggers-field-catalog.md

@@ -0,0 +1,17 @@
+# Triggers Field Catalog (skill pointer)
+
+**Canonical authority**: [`super-legal-mcp-refactored/src/config/xlsxTemplates/README.md` §3 — Triggers field catalog](../../../../super-legal-mcp-refactored/src/config/xlsxTemplates/README.md#3--triggers-field-catalog)
+
+The canonical README enumerates:
+
+- **3 available trigger fields** that `_dispatcher.js evaluateTriggers()` reads from `sessionContext`: `invokedModels` (array), `dealType` (string), `dealSize` (number)
+- **6 supported ops**: `eq`, `in`, `gte`, `lte`, `contains`, `count_gte` — with type-compatibility rules + worked examples
+- **Triggers composition** (`any` vs `all` semantics + priority ranges 10-90)
+- **Dispatch priority matrix** for the current 5 production templates
+- **Extension workflow**: how to add a new trigger field (caller populates sessionContext + update README + no dispatcher edit needed)
+
+When the skill's `validate-template.py` warns "Unknown trigger field" (CHECK 18), it's saying the field isn't listed in §3. Either fix the typo OR extend §3 with the new field if intentionally adding one.
+
+## Why this skill reference is thin
+
+The canonical doc lives alongside the templates it describes (`src/config/xlsxTemplates/README.md`), so the next engineer touching `_dispatcher.js` sees it in the same `ls` listing. Skill references duplicating content would drift; this pointer keeps the skill as the entry point but defers authority to the colocated README.

.claude/skills/xlsx-workbook-template-creator/scripts/create-template.sh

@@ -119,6 +119,12 @@ if [ "$DRY_RUN" = "1" ]; then
   echo "  - Add: ${CAMEL_NAME} to ALL_TEMPLATES array"
   echo "Multi-turn?               $([ $MULTI_TURN -eq 1 ] && echo yes || echo no)"
   echo "Priority:                 $PRIORITY"
+  echo ""
+  echo "▶▶▶ READ FIRST (PR #143 canonical authority) ▶▶▶"
+  echo "  • super-legal-mcp-refactored/src/config/xlsxTemplates/README.md"
+  echo "    └─ template schema, 3 trigger fields, 12 layouts, dispatch priority matrix"
+  echo "  • super-legal-mcp-refactored/prompts/xlsx-templates/README.md"
+  echo "    └─ prose sidecar design, consumption flow, 10 pitfalls, multi-turn truncation"
   exit 0
 fi
 
@@ -270,7 +276,7 @@ export const def = {
   citationDiscipline: XLSX_TEMPLATE_BASE.SOURCES_SHEET_SPEC,
   cellColoring: XLSX_TEMPLATE_BASE.CELL_COLORING,
 
-  // NO phaseSplit — this template runs as single-turn through xlsxRenderer/index.js:208
+  // NO phaseSplit — this template runs as single-turn through xlsxRenderer/index.js:210
 };
 
 export default { def };
@@ -322,16 +328,25 @@ echo "Prose sidecar(s):    $PROSE_DIR/${ID}-*.md"
 echo "Registry patched:    $INDEX_FILE"
 echo "==================================================="
 echo ""
+echo "▶▶▶ READ FIRST (PR #143 canonical authority) ▶▶▶"
+echo "  • super-legal-mcp-refactored/src/config/xlsxTemplates/README.md"
+echo "    └─ template schema, 3 trigger fields, 12 layouts, XLSX_TEMPLATE_BASE reference,"
+echo "       dispatch priority matrix, extension workflow"
+echo "  • super-legal-mcp-refactored/prompts/xlsx-templates/README.md"
+echo "    └─ prose sidecar design, consumption flow, 10 pitfalls, multi-turn truncation"
+echo ""
 echo "NEXT STEPS:"
-echo "  1. Edit $TARGET_FILE — replace all TODO markers"
-echo "  2. Edit prose sidecar(s) at $PROSE_DIR/${ID}-*.md — replace TODO content"
+echo "  1. Edit $TARGET_FILE — replace all TODO markers (consult templates README §3 for triggers, §4 for layouts)"
+echo "  2. Edit prose sidecar(s) at $PROSE_DIR/${ID}-*.md — replace TODO content (consult prompts README §3-§6)"
 echo "  3. Read references/audit-rules-cookbook.md if overriding XLSX_TEMPLATE_BASE defaults"
 if [ "$MULTI_TURN" = "1" ]; then
-  echo "  4. Read references/phase-budget-calibration.md for phase budget tuning"
+  echo "  4. Read references/phase-budget-calibration.md for phase budget tuning (PR #134 isolation principle)"
 fi
 echo "  5. Run: python3 .claude/skills/xlsx-workbook-template-creator/scripts/validate-template.py $ID"
 echo "  6. Run: bash .claude/skills/xlsx-workbook-template-creator/scripts/add-test-fixtures.sh $ID"
 echo "  7. Run: cd super-legal-mcp-refactored && node test/sdk/xlsx-renderer-integration.test.js"
 echo "  8. Verify gather.js sets spec.callerCategory='xlsx_$([ $MULTI_TURN -eq 1 ] && echo multi || echo single)_turn'"
 echo "     for this template's invocations (CRITICAL — PR #138 retroactive lesson)"
+echo "  9. Bump hard-coded '5 templates' count in test/sdk/xlsx-renderer-integration.test.js:120"
+echo "     (registry size assertion — adding 6th template requires updating this)"
 echo ""

.claude/skills/xlsx-workbook-template-creator/scripts/validate-template.py

@@ -196,7 +196,7 @@ def main():
 
         print("  [Multi-turn template detected — uses multiTurnOrchestrator.js]")
     else:
-        print("  [Single-turn template — no phaseSplit; uses xlsxRenderer/index.js:208]")
+        print("  [Single-turn template — no phaseSplit; uses xlsxRenderer/index.js:210]")
 
     # Check 13: registered in index.js
     if INDEX_FILE.exists():
@@ -309,6 +309,42 @@ def main():
               "Found arrow function or 'function' keyword in template body — templates must be declarative; "
               "logic belongs in renderer (nodeAudit.js, mergeWorkbooks.js)")
 
+    # PR #143 — CHECK 18: trigger field catalog (soft WARN if unknown).
+    # Canonical set documented in src/config/xlsxTemplates/README.md §3.
+    # Engineer can intentionally extend (add new field to dispatcher caller's
+    # sessionContext + update README §3); warning surfaces the assumption.
+    KNOWN_TRIGGER_FIELDS = {'invokedModels', 'dealType', 'dealSize'}
+    trigger_fields_used = set(re.findall(r"field:\s*['\"]([a-zA-Z_][a-zA-Z0-9_]*)['\"]", src))
+    unknown_fields = trigger_fields_used - KNOWN_TRIGGER_FIELDS
+    if trigger_fields_used:
+        check(
+            f"All trigger fields are in canonical catalog ({sorted(trigger_fields_used)})",
+            len(unknown_fields) == 0,
+            f"Unknown trigger field(s): {sorted(unknown_fields)} — known set: {sorted(KNOWN_TRIGGER_FIELDS)}. "
+            f"If intentional, update super-legal-mcp-refactored/src/config/xlsxTemplates/README.md §3 to list "
+            f"the new field + caller responsibility, then re-run validator.",
+            severity="warning",
+        )
+
+    # PR #143 — CHECK 19: layout catalog (soft WARN if unknown).
+    # Canonical set documented in src/config/xlsxTemplates/README.md §4 and exported from _layouts.js LAYOUTS.
+    # Engineer can intentionally extend (add to _layouts.js + update README §4); warning surfaces the assumption.
+    KNOWN_LAYOUTS = {
+        'cover', 'exec_summary', 'assumptions', 'three_statement', 'dcf', 'comps', 'lbo',
+        'sensitivity_2d', 'risk_register', 'sources_index', 'model_index', 'auto_per_model',
+    }
+    layouts_used = set(re.findall(r"layout:\s*['\"]([a-zA-Z_][a-zA-Z0-9_]*)['\"]", src))
+    unknown_layouts = layouts_used - KNOWN_LAYOUTS
+    if layouts_used:
+        check(
+            f"All sheet layouts are in canonical catalog ({sorted(layouts_used)})",
+            len(unknown_layouts) == 0,
+            f"Unknown layout(s): {sorted(unknown_layouts)} — known set: {sorted(KNOWN_LAYOUTS)}. "
+            f"If intentional, update _layouts.js + super-legal-mcp-refactored/src/config/xlsxTemplates/README.md §4 "
+            f"to enumerate the new layout, then re-run validator.",
+            severity="warning",
+        )
+
     emit_report()
 
 def emit_report():