@luquimbo/bi-superpowers 5.0.0 → 5.0.2

package/CHANGELOG.md

@@ -7,13 +7,491 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.0.2] — 2026-05-08
+
+### Changed — 2026-05-08 (templates folder + Calendario merge)
+
+- Moved the canonical reference template from `examples/smoke-test/pbip-files/template.*`
+  to `templates/sales/sales-template.*` to make room for additional template
+  domains (`templates/<domain>/`). Removed the `examples/smoke-test/` umbrella
+  and the orphaned `super-test.*` Desktop cache. Filename rename to
+  `sales-template.*` was performed via Power BI Desktop "Save As" so the PBIP
+  descriptor JSONs (`.pbip` and `Report/definition.pbir`) were never
+  hand-edited.
+- `templates/` now ships in the npm tarball (added to `package.json` files
+  whitelist). Excluded `**/.pbi/localSettings.json` from the tarball — those
+  files contain DPAPI-encrypted machine-specific Desktop bindings and must not
+  ship.
+- Updated all repo-side references (skills, AGENTS.md, README.md,
+  ARCHITECTURE.md, CONTRIBUTING.md, validation registry) to point at the new
+  `templates/sales/` location.
+- Merged the `Calendar` Power Query helper into the loaded `Calendario` Date
+  Table. `Calendario` is now rolling (ends at `Today` adjusted by the
+  `ZonaHoraria` parameter) and exposes 7 hidden 4-4-5 fiscal columns
+  (`Fiscal445Year`, `Fiscal445MonthNr`, `Fiscal445QuarterNr`,
+  `Fiscal445SemesterNr`, `Fiscal445MonthKey`, `Fiscal445QuarterKey`,
+  `Fiscal445SemesterKey`) consumed by `Aux Períodos`. The `Calendar` named
+  expression was deleted; `Aux Períodos` rebound to `Calendario` and renamed
+  `[Date]` → `[Fecha]` references.
+
+### Removed — 2026-05-08 (orphan measures in sales template)
+
+- Deleted 5 unused measures from `Métricas`: `Tipo de cambio seleccionado`,
+  `Ventas brutas`, `Métrica seleccionada`, `Color de tarjeta de tendencia`,
+  `Color de barras de tendencia`. Audit confirmed zero consumers in report
+  visuals, other measures, calculation items, or UDFs. Total measure count:
+  32 → 27.
+
+### Fixed — 2026-05-08 (release readiness review)
+
+- Updated all template-reference guidance to match the current smoke-test
+  template: `Métricas` is the dedicated metrics table, measure display folders
+  are one-level (`Auxiliar`, fact-table folders, `Ratios`), base currency flows
+  through `MonedaBase` + `Modelo Configuración[ValorTexto]`, and exchange rates
+  use `Tipo de cambio[TipoCambioBase]`.
+- Tightened the PBIR field-swap exception wording so agents cannot interpret it
+  as permission to hand-patch `visual.json`; only the dedicated plugin command
+  may update data-binding nodes, with dry-run, backup, and validation.
+- Changed the Tabular Editor helper scripts so BPA runs do not silently install
+  TE2. Installation now requires explicit `-Install` / `-InstallTabularEditor`
+  after user consent, supports `GITHUB_TOKEN` for GitHub API limits, and fails
+  instead of guessing when multiple active Power BI Desktop workspaces are
+  reachable.
+- Updated public package metadata and CLI install summaries from the old
+  "3 skills" wording to the current 6-skill contract.
+
+### Changed — 2026-05-08 (skill rules: PBIP read-only + template-as-reference)
+
+- Cemented two cross-cutting invariants across all 6 skills (`bi-start`,
+  `bi-kickoff`, `bi-modeling`, `bi-dax`, `bi-performance`, `bi-connect`):
+  - **PBIP files are read-only**, with the single allowed exception being
+    the plugin-owned field-swap/rebind command that replaces source
+    fields/measures with target fields/measures in *existing template visuals*
+    (preserving visual type, layout, formatting, interactions, IDs, theme, and
+    bookmarks).
+  - **Template is the reference**: skills replicate the BISuperpowers
+    smoke-test template's patterns (Auto Date/Time off, marked Date Table,
+    `Métricas` measure table, one-level display folders, Sallieri period
+    comparison via `Aux Comparaciones`, parameterizable currency via
+    `MonedaBase` + `Modelo Configuración` + `Tipo de cambio`, dynamic
+    dimensions via `Aux Dimensiones ventas` field parameters,
+    calculation-group time intelligence, IBCS-aligned theme) in new projects
+    and audit/migrate existing projects toward them.
+- Added "Template Patterns to Replicate" sections to `/bi-modeling` and
+  "Template DAX Patterns to Replicate" to `/bi-dax` with concrete pattern
+  references and an audit checklist for existing projects.
+- Surfaced both invariants at the top of `AGENTS.md` (Project Overrides).
+
+### Fixed — 2026-05-08 (slash commands for new skills)
+
+- `COMMAND_SKILLS` in `bin/lib/generators/claude-plugin.js` was missing
+  `bi-modeling`, `bi-dax`, and `bi-performance`, so the build was emitting
+  Claude Code slash-command files only for the 3 original skills. Fixed —
+  all 6 skills now generate `commands/<name>.md`.
+
+### Fixed — 2026-05-08 (docs accuracy: skill counts and retired references)
+
+- README.md, AGENTS.md, GETTING-STARTED.md, ARCHITECTURE.md updated from
+  "3 / 4 skills" to **6 skills**. Removed lingering references to the
+  retired `leverio-workflow` skill from GETTING-STARTED.md and
+  ARCHITECTURE.md (skill list and generated tree).
+
+### Changed — 2026-05-08 (template display folders)
+
+- Flattened template measure display folders to one level: `Auxiliar` for helper
+  measures, `Ventas` for fact-table measures, and `Ratios` for percentage and
+  average calculations. Removed nested display-folder paths from the semantic
+  model.
+
+### Changed — 2026-05-08 (template currency symbols)
+
+- Changed the template USD display symbol from `$US` to `$` and simplified the
+  currency formatting UDFs so monetary formats and compact labels render the
+  selected `Monedas[Símbolo]` directly.
+
+### Changed — 2026-05-08 (template sample dataset queries)
+
+- Migrated the smoke-test template sample dataset tables (`Ventas`,
+  `Clientes`, `Productos`, `Canales`, `Monedas`, and `Tipo de cambio`) from DAX
+  calculated tables to Power Query/M partitions so learners see the star-schema
+  sample data as loaded query data. Semantic helper tables remain in DAX where
+  they model template behavior rather than source data.
+
+### Added — 2026-05-08 (bi-performance skill + Tabular Editor 2 integration)
+
+- New `/bi-performance` specialist skill: holistic performance diagnostician
+  with the discipline "measure first, optimize second". Routes by symptom
+  (slow page, slow measure, slow refresh, large model, capacity pressure)
+  through dedicated phases for Performance Analyzer, DAX query timing
+  (Storage Engine vs Formula Engine split), VertiPaq audit via `INFO.*` DMVs,
+  refresh diagnostics (incremental refresh patterns), and Fabric Capacity
+  Metrics. Includes an Anti-patterns table and Healthy Performance Targets
+  reference (page load, query duration, refresh, model size, capacity CU).
+- **Tabular Editor 2 integration**: bundled `scripts/install-tabular-editor.ps1`
+  detects or installs TE2 (free, MIT) to `%LOCALAPPDATA%\TabularEditor\` with
+  detect-then-prompt UX (never silent-install). `scripts/run-bpa.ps1` runs
+  Microsoft's Best Practice Analyzer rules against the open Desktop instance,
+  auto-detecting the AS port from `msmdsrv.port.txt` and caching the rules
+  JSON for 7 days. `/bi-modeling` references this integration as an optional
+  deeper audit layer.
+- Updated `/bi-start` menu to show all 5 specialist skills.
+
+### Added — 2026-05-08 (bi-dax skill)
+
+- New `/bi-dax` skill: DAX authoring, debugging, and optimization. Covers
+  variables, DIVIDE, BLANK propagation, filter context teaching, Storage Engine
+  vs. Formula Engine, calculation groups (standard time intelligence items,
+  ordinal, double-application guard), advanced patterns (Sallieri period
+  comparison, dynamic field parameters, currency conversion, semi-additive
+  measures, RANKX), performance anti-patterns, and live model introspection via
+  `INFO.*` DMVs. Validates every non-trivial formula with `dax_query_operations`
+  before committing. Writes all measures through the Power BI Modeling MCP.
+- Updated `/bi-start` menu to show all 4 specialist skills.
+
+### Added — 2026-05-08 (bi-modeling skill)
+
+- New `/bi-modeling` skill: Power BI semantic model design, audit, and DAX
+  authoring. Covers star schema design (grain → fact → dimensions → relationships
+  → first measure slice), model health audits with CRÍTICO/ADVERTENCIA/INFO
+  severity tiers, targeted modeling tasks, DAX pattern reference, and an
+  anti-patterns table. Operates exclusively through the Power BI Modeling MCP;
+  enforces Auto Date/Time disablement, Date Table marking, and
+  `discourageImplicitMeasures` on every model it touches.
+- Updated `/bi-start` menu to show all 3 specialist skills
+  (`bi-kickoff`, `bi-modeling`, `bi-connect`).
+
+### Changed — 2026-05-08 (template base currency parameter)
+
+- Added a `MonedaBase` Power Query parameter to the smoke-test template and
+  made it the single source for both model base currency and default
+  visualization currency. Currency conversion now reads exchange rates against
+  the configured base currency instead of treating `USD` as an untracked DAX
+  convention.
+
+### Changed — 2026-05-08 (template currency conversion)
+
+- Aligned the smoke-test template currency model with the Sallieri pattern:
+  `Monedas` is now a pure currency selector, `Tipo de cambio` owns date-level
+  exchange rates, and the conversion and format UDFs use the Sallieri USD
+  short-circuit, blank handling, same-currency short-circuit, `Monetaria` flag,
+  and `$US` formatting behavior.
+
+### Changed — 2026-05-08 (Git coaching in BI workflows)
+
+- Clarified the agent convention that Power BI users should be coached toward
+  developer-grade Git habits: after meaningful saved Desktop changes, agents
+  should review diffs, explain the snapshot, recommend a commit, and offer to
+  create it automatically when the repo is clean and verified.
+
+### Removed — 2026-05-08 (repo workflow skill)
+
+- Removed `leverio-workflow` from the shipped plugin contract. The five-file
+  project workflow remains an internal maintainer convention for this repo, but
+  the public plugin now ships only the three BI skills: `bi-start`,
+  `bi-kickoff`, and `bi-connect`.
+
+### Added — 2026-05-07 (canonical theme source)
+
+- Added `theme/BISuperpowers.json` as the canonical source of truth for the
+  Power BI JSON theme, separate from the PBIP copy that Desktop can overwrite.
+  Theme changes should be edited here and then copied into the PBIP location
+  when deploying to Desktop.
+- Included `theme/` in the npm package so the canonical theme source ships with
+  the CLI.
+- Corrected semantic colors to Tremor values: `good: #22C55E`, `bad: #EF4444`,
+  `neutral: #6B7280`; also updated `kpi.goodColor` and
+  `waterfallChart.increaseFill` to match.
+- Corrected `callout` font size from 32 → 20 pt and font face to DIN; `title`
+  font face from DIN → Segoe UI Semibold at 10 pt.
+- Corrected `cardVisual.referenceLabelValue.valueFontSize` from 8 → 10 pt.
+- Set `cardVisual.padding` to `6/3/6/3` (was `0/0/0/0`).
+
+### Changed — 2026-05-06 (PBIR field-swap exception)
+
+- Refined the PBIP artifact editing rule: the only report-side exception is a
+  plugin-owned field-swap/rebind command for existing template visuals. It may
+  write PBIR only for data binding nodes (`projections`, `prototypeQuery`, query
+  refs, field parameters, and sort/filter field references when required), with
+  dry-run, backup, validation, and explicit source-to-target mapping. Bookmarks,
+  layout, formatting, interactions, IDs, theme, slicer/card settings, and other
+  report artifacts remain protected from ad hoc JSON edits.
+
+### Fixed — 2026-05-06 (bi-kickoff MCP write rule)
+
+- Tightened `bi-kickoff` so a missing Modeling MCP means connect first or stop;
+  it must not be interpreted as permission to fall back to direct TMDL/PBIP
+  file edits.
+
+### Changed — 2026-05-06 (PBIP artifact editing rule)
+
+- Codified the post-`bi-report` rule that PBIP files are version-control
+  snapshots, not an agent authoring surface. Semantic-model changes must go
+  through the Power BI Modeling MCP; report and visual changes are manual Power
+  BI Desktop work. Agents must not patch PBIR `.Report/**` JSON, visual
+  bindings, slicer/card settings, themes, or report resources directly.
+- Added the only planned exception: a future plugin-owned field-swap/rebind
+  action for template adaptation. It must replace fields in existing visuals
+  through an explicit mapping and preserve visual type, layout, formatting,
+  interactions, IDs, and theme; agents still must not improvise JSON patches.
+
+### Changed — 2026-05-06 (template period comparison queries)
+
+- Updated the smoke-test template semantic model with the Sallieri period
+  comparison query tables (`Calendar`, `Calendar Type`, `Calendar Periods`,
+  `Calendar Comparisons`, `Calendar Axes`, and `Modelo Configuración`) so the
+  fixture can exercise the same comparison-period logic as the client model.
+
+### Removed — 2026-05-05 (retired report authoring skill)
+
+- Removed the retired PBIR report-authoring skill from package source,
+  generated skills, slash commands, manifests, validation cases, and public
+  docs. The local user-level copy is intentionally left outside the package so
+  this repository no longer installs or ships that workflow.
+
+### Fixed — 2026-05-04 (validate-pbir tabOrder false-positive)
+
+- **`validate-pbir.js` `position-number` rule** loosened to match Power BI
+  Desktop's actual save behavior: `tabOrder` is now optional. Desktop
+  omits `tabOrder` from the `position` block on visuals it considers
+  non-interactive (cards, decorative elements). The validator
+  previously required it, producing 9 false-positive errors per save
+  cycle on the smoke-test template. New behavior: required fields are
+  `x, y, z, height, width`; `tabOrder` is required to be a finite
+  number ONLY when present. Two new test cases lock in the contract
+  (`absent tabOrder is valid`, `present-but-non-finite tabOrder is
+  still an error`). Smoke test goes from 10 errors → 0 errors.
+
+### Added — Session G 2026-05-03 (Semantic-model deep audit, "best template in the world")
+
+- **`retired-report-skill` MANDATORY RULES 18-20** codifying the three highest-impact
+  cleanups every pro template must ship with:
+  - **RULE 18 — Disable Auto Date/Time**: model annotation
+    `__PBI_TimeIntelligenceEnabled = 0` + cascade-delete every
+    `LocalDateTable_*` and `DateTableTemplate_*`. The lab template carried
+    8 phantom tables (~64 junk columns + 7 phantom relationships).
+    Verified via `INFO.ANNOTATIONS()` DMV (TMDL export hides the
+    annotation but the DMV proves it).
+  - **RULE 19 — Mark real calendar as Date Table**: one MCP call
+    (`table_operations.MarkAsDateTable` on `Calendario.Fecha`); without
+    it, Time Intelligence (`DATEADD`, `SAMEPERIODLASTYEAR`, calculation
+    groups using DATEADD) silently returns wrong results.
+  - **RULE 20 — Every dimension gets a user hierarchy**: drill-down is
+    a free Power BI feature that turns flat field lists into explorable
+    models. Created `Jerarquía de fechas / productos / geográfica /
+    canales` in the lab template (Año→Trimestre→Año mes→Semana→Fecha,
+    Categoría→Subcategoría→Producto, País→Segmento→Cliente, Tipo de
+    canal→Canal).
+
+### Changed — Lab smoke test (template.pbip) Session G
+
+- **Auto Date/Time disabled** model-wide. 8 phantom tables removed
+  (`DateTableTemplate_c35f5a13` + 7 `LocalDateTable_*`), 7 phantom
+  relationships gone, ~940 net lines deleted from TMDL on disk.
+- **`Calendario` marked as Date Table** with `Fecha` as the date column.
+- **`Métrica Seleccionada` → `Métrica seleccionada`** (consistency with
+  the rest of the model's Sentence-case capitalization).
+- **`Calendario[Año mes]`** now has explicit `sortByColumn: 'Orden año
+  mes'` (was relying on lexicographic order — bug-prone).
+- **`Calendario[Semana]`** had a spurious `formatString: 0` left over from
+  when it was an Int64 — removed (the column has been a String "S48
+  (24/12)" since the user-friendly labels rework).
+- **`Ventas[VentaId]`** flipped from `summarizeBy: count` to
+  `summarizeBy: none` (defensive; the table is already hidden but the ID
+  shouldn't be summable in any code path).
+- **Audit verdict on legacy `Aux Métricas` columns** (Monetaria,
+  Acumulado, Media móvil, Tipo de métrica, Agregación predeterminada,
+  Base acumulable, Descripción): kept. They are hidden, don't degrade
+  performance (≤6 unique values), document Salieri's design intent, and
+  remain available for future calculation groups. `Permite promedio` and
+  `Permite acumulado` confirmed in active use by the `Aux Vista del
+  valor` calculation group.
+
+### Added — Session F continuation 2026-05-02 PM (Field Parameters + UDF refactor)
+
+- **`retired-report-skill` MANDATORY RULES 15-17**: field-parameter binding contract,
+  `__HasCalendarAxis` enumeration rule for router measures, and
+  dynamic-format-string contract via `formatStringExpression`.
+- **New reference doc** `src/content/skills/retired-report-skill/references/field-parameters.md`:
+  TMDL `kind:2` ParameterMetadata + NAMEOF pattern, visual.json
+  `fieldParameters[]` projection sibling, end-to-end calculated-table →
+  Field-Parameter conversion checklist, and seven failure modes
+  catalogued from the lab debugging session.
+- **New reference doc** `src/content/skills/retired-report-skill/references/dynamic-axis-measures.md`:
+  `__HasCalendarAxis` ISINSCOPE pattern, `FormatStringExpression` via
+  selector-table format column, period-aware `CalendarContext()` usage,
+  and end-to-end checklist for shipping a router measure.
+- **New helper script**
+  `src/content/skills/retired-report-skill/scripts/save-powerbi-window.ps1`:
+  programmatic `Ctrl+S` send to the active PBI Desktop window. Mirrors
+  Codex's flow via Win32 SetForegroundWindow + wscript.shell SendKeys
+  "^s". Use BEFORE any `taskkill` when there are uncommitted MCP model
+  edits — otherwise they are silently lost.
+- **`bi-connect` MANDATORY RULE 8**: "MCP MODEL EDITS ARE IN-MEMORY ONLY
+  — SAVE BEFORE CLOSE." Codifies the Codex pattern: either ask the
+  user for `Ctrl+S` confirmation or drive save via the new helper.
+  `taskkill /F /IM PBIDesktop.exe` without a prior save discards every
+  MCP edit silently.
+- **`retired-report-skill` MANDATORY RULE 3 (extended)**: companion save-before-close
+  rule for mixed cycles. Order of operations: (1) MCP edits, (2) save,
+  (3) taskkill, (4) edit visual.json, (5) relaunch.
+
+### Changed — lab smoke test (template.pbip)
+
+- **`Aux Ejes temporales` is now a real Field Parameter** (`kind: 2`
+  ParameterMetadata + NAMEOF references to `Calendario[Fecha / Semana /
+  Mes / Trimestre / Año]`). Slicer-driven dynamic axis works on the
+  Evolución page line chart and pivot table. Same pattern as Salieri's
+  `Calendar Axes`.
+- **`Calendario` columns now display user-friendly labels in their
+  ORIGINAL columns** (no `Etiqueta` suffix per Lucas's preference):
+  `Fecha` formatString "ddd d/M" → "mar 5/12"; `Mes` value "Ene '26"
+  sorted by `Orden año mes`; `Trimestre` value "Q1 '26" sorted by new
+  `Trimestre Orden` column; `Semana` value "S48 (24/12)" with the
+  Monday-of-week date, sorted by new `Semana Orden` column.
+- **Two new UDFs** in template's model:
+  - `FormatoMetricaSeleccionada()` — returns the format string
+    configured for the selected metric (`SELECTEDVALUE('Aux Métricas'[Formato], "#,0")`).
+    Used as `formatStringExpression` on `Actual`, `Anterior`, `Variación`.
+  - `EjeCalendarioEnContexto()` — TRUE if any `Calendario` column is in
+    scope (Fecha / Año / Trimestre / Mes / Año mes / Semana). Centralized
+    so adding a new calendar column is one edit, not N.
+- **Router measures `Actual` / `Anterior` refactored** to call the two
+  new UDFs instead of inlining the ISINSCOPE chain and the
+  `SELECTEDVALUE([Formato])`. Less code duplication; one point of
+  change for future granularities.
+
+### Changed
+
+- **Lab smoke test — auxiliary tables renamed for clarity** (Session F continuation,
+  2026-05-02). Eight model tables renamed via the `powerbi-modeling-mcp` `Rename`
+  operation (auto-updates DAX expressions and relationships) plus a JSON-aware
+  bulk replace across all PBIR `definition/**.json` files (224 `Entity` refs +
+  236 qualified `queryRef`/`metadata` refs). Renames:
+  - `Comparaciones` → `Aux Comparaciones`
+  - `Períodos` → `Aux Períodos`
+  - `Vista de calendario` → `Aux Vista de calendario`
+  - `Ejes temporales` → `Aux Ejes temporales`
+  - `Vista del valor` → `Aux Vista del valor`
+  - `Vista temporal` → `Aux Vista temporal`
+  - `Métricas` → `Aux Métricas` (heart of the model — 26 measures, central selector)
+  - `TipoCambio` → `Tipo de cambio` (cosmetic; spaces are friendlier)
+
+  Convention: every disconnected/auxiliary selector or catalog table now
+  carries an `Aux ` prefix so they group together in the PBI Desktop Fields
+  pane and are visually distinct from real fact/dim tables (`Ventas`,
+  `Productos`, `Clientes`, `Canales`, `Fecha`, `Monedas`). DAX measures still
+  live inside `Aux Métricas` — the rename does not separate them.
+
+  Verified end-to-end: model DAX (`CALCULATE([Actual], 'Aux Comparaciones'[Comparación EN] = …)`)
+  returns expected values; visual rendering confirmed via
+  `capture-powerbi-window.ps1` after reopen.
+
+### Added
+
+- **`retired-report-skill` repair tooling**: new `scripts/repair-pbir-layout.js` script.
+  Page-scoped, dry-run by default, classifies slicers (normal / off-canvas /
+  parked at `9000,9000`) and repairs only clearly broken slicers into a
+  deterministic top filter bar. Preserves bindings, objects, selection mode,
+  z-order, and tabOrder. 600+ lines of tests covering classification,
+  dry-run vs write modes, and cross-page issue isolation.
+- **`validate-pbir.js` page-scoped + Git-aware modes**: `--page <name|displayName>`
+  filters to a single page; `--changed-only` validates only visual files
+  changed against `HEAD` in a Git worktree. New JSON output shape with
+  `summary.errors`, `summary.warnings`, and `issues[]`. Existing full-report
+  behavior unchanged when both flags are absent.
+- **PBIP-native template lab** (smoke test): rewrote `BISuperpowers.json`
+  theme (+3500 lines of authentic tokens), added
+  `references/reference-report-benchmark.md`, expanded
+  `references/layouts/sales.md`, and added
+  `scripts/capture-powerbi-window.ps1` for benchmark screenshots.
+- **Per-tool approval gates for Codex**: `~/.codex/config.toml` writer now
+  emits `[mcp_servers.powerbi-modeling-mcp.tools.<op>] approval_mode = "approve"`
+  for every write operation in `CODEX_POWERBI_WRITE_TOOLS`. Re-install dedup
+  pattern updated to also strip child sections.
+
+### Changed
+
+- **Power BI Modeling MCP launcher** now spawns the official Microsoft
+  executable with `--readwrite --skip-confirmation` (previously `--start`).
+  The Codex-side per-tool approval is now the only gate that prompts the
+  user, so the MCP-level confirmation can be skipped safely.
+- **Smoke test fixture renamed**: `examples/smoke-test/pbip-files/super-test.pbip`
+  is now `template.pbip`; `validation/projects/super-test.json` is now
+  `validation/projects/template.json`. CLI examples and docs updated to match.
+- **Documentation realignment**: `AGENTS.md`, `CLAUDE.md`, `README.md`, and
+  `ROADMAP.md` now position **Codex as the primary end-to-end validation
+  baseline**. Other agents (Claude Code, GitHub Copilot, Gemini CLI, Kilo Code,
+  Claude Desktop) are documented as compatibility targets.
+- **Single-session dev workflow** is now the default convention. The
+  `obra/superpowers` worktrees convention is preserved in `ROADMAP.md` for
+  emergency-only use.
+- **Documentation maintenance contract** (this commit forward): every commit
+  must review and update `CHANGELOG.md` (Unreleased), `ROADMAP.md` (session
+  log + DONE items), `AGENTS.md`, `CLAUDE.md`, and `README.md` where
+  relevant. See "Documentation Maintenance" in `AGENTS.md`.
+- **Atomic commits strategy + push policy** (this commit forward): the agent
+  commits autonomously when a coherent unit lands clean (tests/lint/format
+  green, docs contract honored). The agent NEVER pushes without explicit
+  user authorization — commits accumulate locally and the agent asks
+  _"Hay N commits listos para pushear, ¿pusheo?"_. Full strategy +
+  anti-triggers documented in `AGENTS.md` → "Atomic Commits Strategy".
+
+#### retired-report-skill skill — Refe pages debugging + new MANDATORY RULES (Session F)
+
+- **Three new MANDATORY RULES on `retired-report-skill` SKILL.md**:
+  - **R12** — check `report.json` settings before first run;
+    `hideVisualContainerHeader: true` plus the Salieri-parity baseline.
+  - **R13** — filter literals must match the locale of the target column
+    (Comparaciones[Comparación] vs Comparaciones[Comparación EN]).
+  - **R14** — time axes use Fecha[Fecha] (daily) or Fecha[Año mes]
+    (monthly); never Fecha[Semana] (week-of-year integers lose chronology
+    and crash across year boundaries).
+- **New reference** `src/content/skills/retired-report-skill/references/generic-template-pages.md`:
+  three tested page compositions (Resumen Ejecutivo, Comparativa de
+  Períodos, Tendencias de Métricas) with full layout coordinates,
+  visual types, container titles, and `--bind` field maps. Plus a
+  7-pitfall "Common gotchas" section captured during Refe-pages debugging.
+
+#### Lab smoke test — Refe pages improved + 2 new generic-template pages
+
+Worked exclusively in `examples/smoke-test/pbip-files/template.pbip`. Six
+focused commits, all validated visually via `capture-powerbi-window.ps1`
+after each close-write-open cycle.
+
+- **`92415ae`** — `report.json` settings aligned to Salieri reference
+  (`hideVisualContainerHeader: true` + 2 related), and
+  `visualContainerObjects.title` blocks stripped from all 14 cardVisuals
+  on the two Refe pages so the new setting takes effect.
+- **`f1d413d`** — Refe KPI card filters repointed from
+  `Comparaciones[Comparación]` (Spanish, never matched the English
+  literals Codex passed) to `Comparaciones[Comparación EN]`. Two
+  "This quarter" cards had a "This month" filter literal — copy-paste
+  bug, fixed.
+- **`10c1d89`** — Refe Metrics Trends time axis: line chart Category
+  `Fecha[Semana]` → `Fecha[Fecha]`; pivot Columns `Fecha[Semana]` →
+  `Fecha[Año mes]`. Replaces illegible 1-52 week-number labels with
+  smooth daily trend + chronological month columns.
+- **(new page)** `resumen_ejecutivo` — 13-visual generic Executive
+  Summary page authored end-to-end via `create-visual.js`. 5-card KPI
+  band + main row + detail row (mix donut + variation by category +
+  top clients).
+- **(new page)** `comparativa` — 12-visual generic Period Comparison
+  page. multiRowCard period-title labels + 4 variation KPIs +
+  lineClusteredColumnComboChart + waterfallChart + pivot matrix +
+  variation-by-product bar chart.
+- Pages.json updated to 6 pages: `resumen_ejecutivo` (active),
+  `6a4808bb8bb9166f49ff` (Refe Metrics, improved),
+  `2be0c041e797b796d115` (Refe Ventas, improved), `comparativa`,
+  `sales_trends` (Codex from-scratch, untouched), `ventas` (Codex
+  from-scratch, untouched). Codex's pages preserved for the
+  Codex-vs-Claude design eval Lucas requested.
 ## [5.0.0] — 2026-04-28
 
 ### Breaking
 
 - Standardized all public slash commands under the `/bi-*` namespace:
   `/project-kickoff` is now `/bi-kickoff`, `/pbi-connect` is now
-  `/bi-connect`, and `/report-design` is now `/bi-report`.
+  `/bi-connect`, and `/retired-report-skill` is now `/retired-report-skill`.
 - Regenerated the Claude Code plugin commands, user-level skills, skill
   manifests, docs, and validation fixtures for the new command names.
 
@@ -31,7 +509,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `super validate-projects` now fails fast when `validation/projects` is missing,
   so running it from the wrong directory cannot false-green with `0 checked`.
 - Generated command and skill edit comments now point folder-based skills at the
-  real source path, for example `src/content/skills/bi-report/SKILL.md`.
+  real source path, for example `src/content/skills/retired-report-skill/SKILL.md`.
 - README update instructions use a neutral project placeholder and the BI Report
   runtime table-of-contents anchor now matches the heading.
 - Historical changelog entries were restored to the command and file names that
@@ -93,19 +571,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - Claude Desktop `.mcpb` builds now bundle folder-based skills as `skills/<name>/SKILL.md`
-  and include `report-design` runtime `references/` plus `scripts/` assets, so installed
+  and include `retired-report-skill` runtime `references/` plus `scripts/` assets, so installed
   Desktop prompts no longer point at missing files.
 - `super scan` now compares source skills against the actual generated Claude Code command
   output, including frontmatter and update-check preamble, eliminating permanent false drift.
-- `report-design` `create-visual.js` now rejects path traversal in `--name` and non-finite
+- `retired-report-skill` `create-visual.js` now rejects path traversal in `--name` and non-finite
   numeric placement flags before writing `visual.json`.
-- `report-design` `validate-pbir.js` now flags non-finite `position` values.
+- `retired-report-skill` `validate-pbir.js` now flags non-finite `position` values.
 - Claude Desktop setup instructions and postinstall output use the canonical
   `powerbi-modeling-mcp` server key.
 - `super sentinel` now watches folder-based skill trees, including `SKILL.md`, `references/`,
   and runtime scripts, and regenerates through the same versioned generator path as
   `super recharge`.
-- Removed stale conditional-formatting release wording from `report-design` source docs.
+- Removed stale conditional-formatting release wording from `retired-report-skill` source docs.
 
 ### Changed
 
@@ -169,13 +647,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   npm package metadata.
 - **Desktop extension build includes folder-based skills** — the `.mcpb`
   extension produced by `super build-desktop` was silently dropping
-  `report-design` (the flagship skill) because the bundler only picked
+  `retired-report-skill` (the flagship skill) because the bundler only picked
   up flat `.md` files. Now uses `loadSkills()` which handles both flat
   and folder-based layouts. 5 regression tests.
 - **Skill trigger parser extracts multiple quoted fragments per bullet** —
   `project-kickoff` went from `triggerCount: 0` to `9` in
   `.claude-plugin/skill-manifest.json`; `pbi-connect` from `5` to `15`;
-  `report-design` from `3` to `9`.
+  `retired-report-skill` from `3` to `9`.
 - **`validate-pbir.js` detects duplicate `visual.name` on the same page** —
   PBI Desktop accepts the file, but filter/bookmark refs collide.
 - **README rewrite**: dual install paths clearly segmented by audience
@@ -278,9 +756,9 @@ bootstrap a new project.
 
 ## [4.0.0] — 2026-04-15
 
-### Breaking — `/report-design` pivoted to CLI-first architecture
+### Breaking — `/retired-report-skill` pivoted to CLI-first architecture
 
-The `/report-design` skill has been rewritten to orchestrate the
+The `/retired-report-skill` skill has been rewritten to orchestrate the
 [`pbi-cli-tool`](https://github.com/MinaSaad1/pbi-cli) CLI (MIT,
 by MinaSaad1) instead of hand-writing PBIR JSON. This is a **breaking
 change** because students now need Python 3.10+ and `pbi-cli-tool`
@@ -329,7 +807,7 @@ removing our most fragile maintenance burden.
 - `project-kickoff.md` PHASE 7 handoff updated to mention CLI prereq
 - `base.md` and `routing.md` descriptions updated
 - `troubleshooting.md` rewritten for CLI-specific errors
-- `report-design` added to `COMMAND_SKILLS` in the generator (now a
+- `retired-report-skill` added to `COMMAND_SKILLS` in the generator (now a
   slash command, not just a reference skill)
 
 ### Credits
@@ -346,7 +824,7 @@ removing our most fragile maintenance burden.
 
 ### Added
 
-- **New skill: `/report-design`.** Authors 3 PBIR report pages directly
+- **New skill: `/retired-report-skill`.** Authors 3 PBIR report pages directly
   from a ready semantic model. Produces Pro-quality visuals — conditional
   formatting, KPI cards with trend coloring, matrix with gradients,
   slicers, sorted bar charts, pixel-perfect 1280×720 grid layout.
@@ -355,11 +833,11 @@ removing our most fragile maintenance burden.
 - **Folder-based skill support.** The skill loader and plugin generator
   now accept skills authored as a folder with `SKILL.md` + `references/`
   + `scripts/` subfolders (Anthropic's skill convention). Used by
-  `/report-design` — the main SKILL.md is a thin orchestrator and the
+  `/retired-report-skill` — the main SKILL.md is a thin orchestrator and the
   agent loads PBIR templates, layouts, and troubleshooting notes on
   demand from `references/`. Ships a `validate-pbir.js` helper under
   `scripts/` that structurally validates a generated `.Report/` folder.
-- `/project-kickoff` now ends with a handoff to `/report-design` once
+- `/project-kickoff` now ends with a handoff to `/retired-report-skill` once
   the model base has 1 fact + 1 dim + 3 measures.
 
 ### Changed
@@ -372,7 +850,7 @@ removing our most fragile maintenance burden.
 PBIR (Power BI Enhanced Report format) is a Microsoft Public Preview
 feature at the time of this release. Students must activate
 **File → Options → Preview features → Power BI Project (.pbip) save
-format (PBIR)** in Power BI Desktop before `/report-design` can write
+format (PBIR)** in Power BI Desktop before `/retired-report-skill` can write
 report files. If Microsoft ships a schema update that breaks our
 templates, run `super upgrade` — we commit to keeping the plugin in
 sync with PBIR changes while the feature is in preview.
@@ -429,7 +907,7 @@ The plugin has been simplified to its core: **Power BI Desktop local development
 
 #### Removed skills (22)
 
-`contributions`, `data-model-design`, `data-modeling`, `data-quality`, `dax`, `dax-doctor`, `dax-udf`, `deployment`, `excel-formulas`, `fabric-scripts`, `fast-standard`, `governance`, `migration-assistant`, `model-documenter`, `power-query`, `query-performance`, `report-design`, `report-layout`, `rls-design`, `semantic-model`, `testing-validation`, `theme-tweaker`.
+`contributions`, `data-model-design`, `data-modeling`, `data-quality`, `dax`, `dax-doctor`, `dax-udf`, `deployment`, `excel-formulas`, `fabric-scripts`, `fast-standard`, `governance`, `migration-assistant`, `model-documenter`, `power-query`, `query-performance`, `retired-report-skill`, `report-layout`, `rls-design`, `semantic-model`, `testing-validation`, `theme-tweaker`.
 
 #### Kept skills (2)