Build Agentic Power BI System (#3, #4)

.agents/skills/agentic-powerbi-system/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: agentic-powerbi-system
+description: Primary System route for durable, decision-first Power BI work, specialist routing, and append-only proof.
+---
+
+# Agentic Power BI System primary route
+
+This is the one primary System skill. It preserves operational truth in
+`workspace/` and uses the existing Power BI specialist skills for the work
+they own. It is a filesystem workflow, not a service or orchestration runtime.
+
+## Route
+
+1. Read `workspace/PROJECT-BRIEF.md` and inspect relevant records in
+   `workspace/history/runs.jsonl` before selecting a route. Match the input
+   reference and route, not copied request text, to find the previous run.
+2. Name the decision, audience, KPI contract, data owner, grain, freshness,
+   RLS owner, refresh/runtime boundary, publish authority, and proof needed.
+3. Route the work to one or more specialist skills:
+   - `powerbi` for business question, decision, KPI definitions, and audit;
+   - `pbip` for PBIP/PBIR/TMDL structure and safe project edits;
+   - `dax` for explicit measures and semantic logic;
+   - `report` for page plans, report states, visuals, filters, and layout;
+   - `fabric` for approved service/workspace checks and publish operations;
+   - `validation` for deterministic local and optional native proof.
+4. Create `workspace/runs/<run-id>/` and write structured `input.json`,
+   `output.json`, and `proof.json`. Failures write `failure.json`; recoveries
+   write `recovery.json` in their new run directory.
+5. Append one JSON object to `workspace/history/runs.jsonl` with the run ID,
+   timestamps, status, input/output/proof references, previous-run relation,
+   and failure/recovery references. Do not rewrite an earlier record.
+6. Promote an example only when the caller explicitly requests curation. The
+   promoted directory must contain its own `README.md` and `proof.json` and
+   must be understandable without importing this repository.
+
+Normal package creation runs the read-only seed guard. It permits the blank
+seed placeholders and deliberate curated examples, but refuses to package a
+non-empty ledger or mutable workspace evidence without changing that evidence.
+
+## Input contract
+
+The route accepts structured references:
+
+```text
+route: audit | page-plan | validation | model | report | service | system-proof
+input_ref: repository path, fixture reference, or approved work reference
+decision_ref: workspace/PROJECT-BRIEF.md or a more specific brief reference
+focus: optional bounded audit focus
+business_question: required for a page-plan route
+target: repository/project path for validation
+promote_example: explicit true only when curation is desired
+```
+
+An input reference identifies the source; it is not a place to store a request
+transcript, credentials, tenant identifiers, or private data.
+
+## Output and proof contract
+
+Every completed route returns or records:
+
+```text
+status
+run_id
+previous_run_id
+previous_run_relation
+decision_ref
+specialist_routes
+output_ref
+proof_ref
+blockers
+warnings
+unavailable_checks
+remaining_risks
+```
+
+An audit must cover semantic model structure, DAX and measure metadata, data
+shaping risks, report storytelling, validation blockers/warnings, and next
+actions. A page plan must return page title, audience and decision, required
+measures/fields, KPI row, main visuals, slicers/filters, interpretation text,
+and a validation checklist. A validation route must run deterministic checks
+first, then report optional native checks only when installed, with blockers,
+warnings, exact paths, unavailable checks, and commands run.
+
+## Power BI gates
+
+The route never substitutes a generated artifact for evidence. Keep each KPI's
+name, DAX, format, interpretation, limitation, source, and business owner
+together. Preserve star-schema grain, explicit relationships, hidden technical
+keys, explicit measures, data ownership, RLS, refresh/runtime, workspace, and
+publish authority. Ask before deleting or rebinding report assets, changing
+`.platform` identity, publishing, overwriting service items, or changing
+access/refresh policy.
+
+## Failure and recovery
+
+Keep a failed run and its evidence available. A recovery is a new run with
+`previous_run_relation: recovery`, `previous_run_id` set to the unresolved
+failed run, and a recovery reference. Recover a failed run at most once. An
+ordinary continuation uses `predecessor`; the first relevant run uses `null`.
+
+## Reference implementation
+
+`workspace/engine/tracer.py` is the deterministic reference route. It proves
+prior-run inspection, success, failure, recovery, append-only history, and
+explicit example promotion with a fixed demonstration clock. It does not claim
+that a live Power BI model, refresh, RLS, Fabric workspace, or publish exists.

.agents/skills/fabric/SKILL.md

@@ -11,15 +11,10 @@ Use this skill when working with Power BI Service or Microsoft Fabric.
 
 ```bash
 fab --version
-fab auth status
-fab ls
 ```
 
-If not logged in, ask the user to run:
-
-```bash
-fab auth login
-```
+Only inspect an approved workspace or item after the user supplies that scope
+and the operation is relevant. A version check alone is not service proof.
 
 ## Path format
 

.agents/skills/pbip/SKILL.md

@@ -37,7 +37,7 @@ Project/
 5. Validate immediately.
 
 ```bash
-node scripts/validate-pbip.mjs .
+node workspace/engine/validate-pbip.mjs .
 pbir validate "Report.Report" --all
 ```
 
@@ -49,7 +49,7 @@ When renaming tables, columns, measures, pages, or visuals, search across:
 - relationships
 - PBIR visual JSON
 - filters and sort definitions
-- report extensions / visual calculations
+- report metadata / visual calculations
 - DAX query files
 - diagram layouts
 

.agents/skills/powerbi/SKILL.md

@@ -42,6 +42,24 @@ Interpretation:
 Validation:
 ```
 
+## Harness-neutral audit contract
+
+Use this contract when the route is an audit. The input is an optional bounded
+`focus` value; it is not a transcript. Return:
+
+```text
+semantic model structure:
+DAX measures and metadata:
+Power Query/data shaping risks:
+report design and storytelling:
+validation blockers/warnings:
+recommended next actions:
+```
+
+Include exact paths for findings and identify the owner or missing evidence for
+each material risk. Keep the business question, decision, grain, KPI owner,
+data boundary, and proof journey visible in the result.
+
 ## Good Power BI habits
 
 - One page should answer one business question.

.agents/skills/report/SKILL.md

@@ -31,3 +31,24 @@ Use direct JSON editing only when the change is small and the structure is clear
 - Folder name and JSON `name` should match.
 - Ask before deleting pages/visuals or bulk formatting.
 - Validate after edits.
+
+## Harness-neutral page-plan contract
+
+Use this contract when planning a page from a `business_question` input. Return
+these fields in order, with names that a caller can consume without a command
+extension:
+
+```text
+page title:
+audience and decision:
+required measures/fields:
+KPI row:
+main visuals:
+slicers/filters:
+business interpretation text:
+validation checklist:
+```
+
+The page title must answer the business question, and the interpretation must
+state the action or decision supported by the evidence. Do not claim data,
+refresh, or visual validation that was not run.

.agents/skills/validation/SKILL.md

@@ -12,7 +12,7 @@ Use this before saying a Power BI task is done.
 1. Local structural validation:
 
 ```bash
-node scripts/validate-pbip.mjs .
+node workspace/engine/validate-pbip.mjs .
 ```
 
 2. PBIR validation when `pbir` is available:
@@ -24,10 +24,12 @@ pbir validate "Report.Report" --all
 3. Fabric/service checks when relevant:
 
 ```bash
-fab auth status
 fab exists "Workspace.Workspace/Model.SemanticModel"
 ```
 
+Run service checks only for an approved target. Do not turn a missing optional
+tool or an unrun service check into a completion claim.
+
 4. Rename cascade checks:
 
 ```bash
@@ -44,6 +46,21 @@ Files changed:
 Remaining risks:
 ```
 
+## Harness-neutral validation contract
+
+The validation route accepts a repository or project `target` (default `.`)
+and runs these steps in order:
+
+1. `node workspace/engine/validate-pbip.mjs <target>`;
+2. `pbir validate <Report.Report> --all` for each report when `pbir` is
+   installed;
+3. approved Fabric existence or item checks only when service scope is
+   relevant.
+
+Return blockers, warnings, exact paths, commands run, unavailable checks, and
+remaining risks. Native Power BI, Fabric, Tabular Editor, and DAX Studio
+results are optional evidence and must never be invented.
+
 ## Common blockers
 
 - invalid JSON

.github/workflows/validate.yml

@@ -1,4 +1,4 @@
-name: Validate template
+name: Validate Agentic Power BI System
 
 on:
   push:
@@ -16,5 +16,6 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 20
+      - run: npm run doctor
       - run: npm run validate
       - run: npm test

.gitignore

@@ -1,8 +1,13 @@
 node_modules/
+__pycache__/
+*.py[cod]
+.pytest_cache/
 .DS_Store
 Thumbs.db
 .env
 .env.*
 !.env.example
-.pi/tmp/
-.pi/sessions/
+.pbi/
+*.pbix
+workspace/state/*
+!workspace/state/.gitkeep

.npmignore

@@ -0,0 +1,6 @@
+__pycache__
+**/__pycache__
+*.pyc
+**/*.pyc
+.pbi/
+*.pbix

AGENTS.md

@@ -1,51 +1,78 @@
-# PowerBI-template
+# Agentic Power BI System
 
-Turn a business question into an owned, validated Power BI model and report.
+Turn a business question into an owned, validated Power BI model, report, and
+decision journey that can retain its operational proof across runs.
+
+## System contract
+
+This repository is the standalone Agentic Power BI System. It follows the
+System Template contract: `workspace/` is persistent operational truth,
+`examples/` contains only deliberate standalone proof, and `docs/` contains
+the public contract and validation recipe. The System is self-contained and is
+not installed into another agent runtime.
+
+The primary route is `.agents/skills/agentic-powerbi-system/SKILL.md`. It first
+inspects relevant records in `workspace/history/runs.jsonl`, routes Power BI
+work through the specialist skills, and preserves input, output, proof,
+failure, recovery, and previous-run references. Request content is represented
+by references and structured facts, never by transcript files. Do not put
+secrets, tenant identifiers, private data, or generated local Power BI state in
+the repository.
 
 ## Start
 
-1. Read `workspace/PROJECT-BRIEF.md` and preserve resolved AIOS or project context.
+1. Read `workspace/PROJECT-BRIEF.md` and preserve any resolved business or
+   project context.
 2. Name the decision, audience, KPI definitions, data owners, refresh/runtime,
    proof, and optional Design-template handoff.
 3. Model first: use a star schema, explicit relationships, hidden technical
    keys, and explicit measures.
 4. Report second: one page per business question, with the decision and its
    evidence ahead of decoration.
-5. Validate every PBIP/PBIR/TMDL edit.
+5. Validate every PBIP/PBIR/TMDL edit and record unavailable optional tools.
 
-## Routes
+## Specialist routes
 
-- `.agents/skills/powerbi/SKILL.md`: business analytics and decision framing
-- `.agents/skills/pbip/SKILL.md`: PBIP/PBIR/TMDL structure
+- `.agents/skills/powerbi/SKILL.md`: business question, decision, KPI, and
+  audit framing
+- `.agents/skills/pbip/SKILL.md`: PBIP/PBIR/TMDL structure and safe edits
 - `.agents/skills/dax/SKILL.md`: measures and semantic logic
-- `.agents/skills/report/SKILL.md`: report composition, states, and filters
-- `.agents/skills/fabric/SKILL.md`: service and Fabric work
-- `.agents/skills/validation/SKILL.md`: completion proof
+- `.agents/skills/report/SKILL.md`: page plans, states, visuals, and filters
+- `.agents/skills/fabric/SKILL.md`: service and Fabric work under authority
+  gates
+- `.agents/skills/validation/SKILL.md`: deterministic completion proof
 
-Pi is optional. Use `scripts/doctor.mjs` and `scripts/validate-pbip.mjs`
-directly in any harness.
+The specialist skills are harness-neutral contracts. The deterministic doctor,
+PBIP validator, Python System engine, and tests live under
+`workspace/engine/` and are callable directly or through the package scripts.
+Normal `npm pack`/publish packaging also runs the read-only seed guard; mutable
+workspace evidence causes an explicit failure and is never removed.
 
 ## Rules
 
 - Keep KPI name, DAX, format, interpretation, limitation, and business owner
   together.
 - Use deterministic validation before visual inspection or guesses.
-- Preserve data ownership, row-level security, refresh, and workspace
-  boundaries.
-- Keep secrets, tenant identifiers, private data, and generated local Power BI
-  state out of Git.
-- Ask before deleting pages or visuals, rebinding, publishing, overwriting
-  service items, changing `.platform` IDs, or changing access/refresh policy.
+- Preserve data ownership, row-level security, refresh, workspace, and publish
+  authority boundaries.
+- Ask before deleting pages or visuals, rebinding reports, changing `.platform`
+  IDs, publishing, overwriting service items, or changing access/refresh
+  policy.
+- Do not invent PBIX/PBIP evidence or require optional Power BI tools that are
+  unavailable.
 - Finish with changed files, validation evidence, unavailable checks, and
   remaining risk.
 
 ## Proof
 
 ```sh
-node scripts/doctor.mjs
-node scripts/validate-pbip.mjs . --ignore-tests
+node workspace/engine/doctor.mjs
+node workspace/engine/validate-pbip.mjs . --ignore-tests
 npm test
+npm pack --dry-run
 ```
 
 Use `pbir validate`, Fabric CLI, Tabular Editor, DAX Studio, Power BI Desktop,
-or `pbi-tools` only when the project and available environment justify them.
+or `pbi-tools` only when the command is truthfully installed and the project
+scope justifies it. Record exact unavailable checks rather than inferring
+their result.