/audit-permissions

name: audit-permissions
description: >-
  Audits existing table permissions on a Power Pages site by analyzing them against site code
  and Dataverse metadata, then GRADES the configuration with deterministic 1–5 scores across
  3 security/usability/correctness categories (9 dimensions). Detection is anchored by a
  recurring-issue catalog so findings and severities stay consistent run-to-run. Generates an
  HTML report with an at-a-glance verdict and per-category scores in the Overview plus a
  single list of **major/minor** issues (each major issue labelled permissions-only or upstream-caused with a short justification), and suggested fixes.
  Use when the user wants to review, verify, check, score,
  or grade table permissions for security issues. Supports SPA and PAC-downloaded non-SPA sites.
user-invocable: true
argument-hint: "[optional: specific table or concern]"
allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, TaskCreate, TaskUpdate, TaskList, Agent
model: opus

> **Plugin check**: Run `node "${PLUGIN_ROOT}/scripts/check-version.js"` — if it outputs a message, show it to the user before proceeding.

Audit Permissions

Audit existing table permissions on a Power Pages code site. Analyze permissions against the site code and Dataverse metadata, then generate a visual HTML report with **deterministic 1–5 category scores**, an advisory verdict, findings, reasoning, and suggested fixes.

The skill has two parts:

1. **Audit checks** (evidence + remediation) — the per-table A–K checklist that compares every permission against real code usage and Dataverse metadata. It is the **primary issue detector**: it catches concrete, code-grounded problems (missing CRUD, append/appendto, `$expand` gaps, broken parent chains, over-provisioned grants) and emits each as a **major/minor** issue with concrete evidence and a fix. 2. **Scoring** (reproducible result) — a **3-category** rubric (9 dimensions) anchored by a **recurring-issue catalog** of fixed detection triggers + severities, followed by a **single consolidation** into root causes and **one batched root-cause attribution** pass for major issues. It turns the findings into **pure-formula 1–5 category scores** so two runs on the same configuration yield the same numbers.

> **Golden rule of scoring:** you only ever **find and label issues** (`major` / `minor`). You do NOT invent the numeric score. The 1–5 numbers come from a **fixed formula** applied to the issue counts (see [Appendix A](#appendix-a--scoring-model)). Same issue set ⇒ same score.

Site type routing

Before reading or executing the workflow below, perform the existing SPA project lookup first.

• Look for `powerpages.config.json` in the current directory or immediate subdirectories using the

existing file-search patterns.

• If found, continue with the existing SPA workflow below.
• Only when that existing SPA lookup finds no `powerpages.config.json`, run:

  node "${PLUGIN_ROOT}/scripts/lib/detect-project-context.js"

• If it returns `siteType: "non-spa"`, read and follow

`${PLUGIN_ROOT}/skills/audit-permissions/references/non-spa-site-workflow.md`. Do not execute the SPA workflow below.

• Otherwise, continue to Step 1 and preserve its existing not-found behavior.

Workflow

1. **Verify Site Deployment** — Check that `.powerpages-site` folder and table permissions exist 2. **Gather Configuration** — Read web roles, table permissions, site code, run the shared schema validator, and build the deterministic preflight cross-reference 3. **Analyze & Discover** — Query Dataverse for relationships and lookup columns using deterministic scripts 4. **Run Audit Checks** — Compare permissions against code usage and best practices (A–K checklist) 5. **Score the Configuration** — Detect/label issues by the 3 categories using the recurring-issue catalog, consolidate to distinct root causes (major/minor), compute the 1–5 category scores and the verdict 6. **Root-cause attribution** — In a single batched pass, label every major issue as permissions-only or caused by an upstream artifact, with a one-sentence justification shown in the report 7. **Generate Report** — Create the HTML report (score overview + findings + inventory) and validate it 8. **Present Findings & Track** — Summarize, record skill usage, and ask the user if they want to fix issues

**Important:** Do NOT ask the user questions during analysis. Autonomously gather all data, then present findings.

Audit completion telemetry

At the very start of Step 1, before site verification, initialize local run state:

node "${PLUGIN_ROOT}/scripts/emit-audit-permissions-telemetry.js" --action start

Parse the JSON stdout and retain its `auditRunId` as `<AUDIT_RUN_ID>` for this invocation. The command does not emit a telemetry event; the existing generic skill invocation event is the start signal. The local run state provides the opaque random ID and start time needed for completion telemetry. Never derive the ID from, or replace it with, a site, environment, tenant, user, path, or report value.

Telemetry is best-effort and must never block the audit. If the initialization command fails or returns no `auditRunId`, continue the audit without completion telemetry. Do not invent an id and do not search local state for the latest run.

On every controlled terminal failure after a run id was returned, close the run before stopping:

node "${PLUGIN_ROOT}/scripts/emit-audit-permissions-telemetry.js" \
  --action complete \
  --runId "<AUDIT_RUN_ID>" \
  --outcome failure \
  --failureStage "<FAILURE_STAGE>"

Use exactly one of these fixed failure stages:

• `site_verification`
• `configuration_gathering`
• `schema_validation`
• `relationship_discovery`
• `audit_checks`
• `scoring`
• `root_cause_attribution`
• `report_rendering`
• `report_validation`
• `metrics_validation`
• `unknown_controlled_failure`

Do not pass error messages, paths, table names, finding content