DataOps-platform/docs/superpowers/plans/2026-07-30-wp11-governance-operational-metrics.md

WP11 Governance Operational Metrics Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [x]) syntax for tracking.

Goal: Deliver five real-time, authorization-aware governance metrics with safe metric-to-detail traceability for the device governance domain.

Architecture: PostgreSQL device assets, authorized source mappings, entity merge events, and quality issues remain authoritative. A read-only metric service calculates each numerator and denominator from current canonical data, applies business-domain authorization in SQL before aggregation or detail retrieval, and exposes explicit definitions plus bounded safe details. The Vue 2 governance dashboard consumes only these APIs and performs no manual metric entry or client-side security filtering.

Tech Stack: Flask, SQLAlchemy/PostgreSQL, existing identity and business-domain authorization services, Vue 2/Vuetify, pytest, Node test runner.

---

Scope and constraints

• Calculate asset completeness, responsibility coverage, entity mapping, issue closure, and issue recurrence for the caller's authorized device scope.
• Define asset completeness as active assets with name, location, organization, responsible person, and at least one authorized active-source mapping divided by active visible assets.
• Define responsibility coverage as active assets with a non-empty responsible person divided by active visible assets.
• Define entity mapping as active visible assets participating on either side of an active, non-rolled-back entity merge divided by active visible assets. Non-admin users may count a merge only when both endpoints are visible.
• Define issue closure as closed visible issues divided by all visible issues; define issue recurrence as visible issues with occurrence_number > 1 divided by all visible issues.
• Return rate=null and status=no_data when a denominator is zero; never present zero as a substitute for unavailable data.
• Apply source business-domain authorization in SQL before aggregation and detail retrieval. Empty source scopes are admin-only.
• Return safe operational fields only. Do not expose asset attribute payloads, issue evidence or message text, source credentials, source configuration, or permission-scope payloads.
• Provide read-only dashboard and detail traceability. Do not add manual metric entry, employee performance scoring, rankings, trends, maturity assessment, generic BI, NL2SQL, or analysis-development capabilities.
• Treat WP11 as device-domain engineering completion only. Enterprise metric thresholds, cross-domain rollout, historical trend baselines, and real-data acceptance remain separate gates.

Task 1: Metric contract and deterministic calculation

Files:

• Create: app/core/data_research/governance_metrics.py

• Create: tests/data_research/test_governance_metrics.py

• [x] Write failing tests for metric definitions, numerator/denominator calculation, six-decimal rounding, zero-denominator no_data, supported state filters, page boundaries, and invalid metric/state rejection.

• [x] Run only the new service test and confirm failure is caused by the absent metric service.

• [x] Implement immutable access, summary, and detail contracts plus GovernanceMetricsService.

• [x] Keep calculation orchestration independent from Flask and SQLAlchemy session globals.

• [x] Re-run only the service test until green.

Task 2: PostgreSQL authorization and safe detail traceability

Files:

• Create: app/core/data_research/governance_metric_repository.py

• Create: tests/integration/test_governance_metrics_postgres.py

• [x] Write a failing PostgreSQL test with authorized, unauthorized, and unscoped device sources; active and retired assets; rolled-back and active merges; and first/recurrent/open/closed issues.

• [x] Prove admin aggregation includes all active device data while a domain viewer sees only authorized sources, assets, merge endpoints, and issues.

• [x] Prove a cross-domain merge is excluded for a non-admin unless both endpoints are visible.

• [x] Prove details contain only the documented safe fields and never asset attributes, issue evidence/messages, source configuration, credentials, or permission-scope payloads.

• [x] Implement authorized-source, visible-asset, active-merge, and visible-issue query boundaries in SQL.

• [x] Implement deterministic metric summaries and paginated state-specific details.

• [x] Run only the PostgreSQL metric integration test until green.

Task 3: Read-only API and permission boundary

Files:

• Modify: app/api/data_development/routes.py
• Modify: app/core/system/permissions.py
• Create: tests/data_research/test_governance_metrics_api.py

• Modify: tests/test_permission_matrix.py

• [x] Write failing API tests for summary, metric/state detail, invalid input, access-context conversion, and repository error handling.

• [x] Write a failing permission test proving both endpoints require governance:read and remain covered by default deny.

• [x] Build the metric access context from the existing canonical identity/business-domain authorization service.

• [x] Add GET /api/development/v1/governance-metrics/summary.

• [x] Add GET /api/development/v1/governance-metrics/details with metric, state, page, and bounded page-size parameters.

• [x] Return validation errors as 400 and unexpected failures through the existing safe API error contract.

• [x] Run only the API and permission tests until green.

Task 4: Governance operations dashboard

Files:

• Create: frontend/src/views/dataGovernance/development/governanceMetrics.vue
• Create: frontend/src/views/dataGovernance/development/governanceMetricsModel.js
• Create: frontend/tests/governance-metrics-model.test.mjs
• Create: tests/data_research/test_governance_metrics_frontend_contract.py
• Modify: frontend/src/api/dataDevelopment.js
• Modify: frontend/src/router/routes.js

• Modify: frontend/src/views/dataGovernance/development/index.vue

• [x] Write failing model tests for percentage formatting, no_data, metric/state labels, safe detail columns, and authorization-scope presentation.

• [x] Write a failing frontend contract test for all five metric cards, explicit formulas, numerator/denominator, real-time/non-manual wording, authorized-scope wording, and detail traceability.

• [x] Add API client methods for summary and details.

• [x] Add a hidden routed dashboard page and a visible development-center entry.

• [x] Render five cards with definition, numerator, denominator, rate, and state-specific detail actions.

• [x] Render paginated safe details without client-side authorization assumptions or raw evidence payloads.

• [x] Use the existing snackbar interface for load failures and keep no_data distinct from 0%.

• [x] Run only the Node model test, frontend contract test, and ESLint on changed frontend files.

Task 5: Documentation, OpenAPI, and release-copy parity

Files:

• Modify: docs/FUNCTION_MODULE_CENSUS_20260726.md
• Modify: docs/DATAOPS_PHASE1_3_MONTH_WORK_PLAN_20260729.md
• Modify: docs/architecture/DATA_MODEL.md
• Modify: docs/architecture/OPENAPI.yaml
• Modify: tests/test_architecture_artifacts.py

• Mirror changed backend files under: deployment/app/

• [x] Document all five formulas, authorization behavior, zero-denominator behavior, safe detail boundaries, and excluded capabilities.

• [x] Mark WP11 device-domain engineering maturity separately from enterprise thresholds and real-data acceptance.

• [x] Update GOV-10 and GOV-11 without claiming employee performance, ranking, trend, maturity, or general BI completion.

• [x] Keep PLT-03 and PLT-04 maturity unchanged because WP11 adds a fixed operational view rather than an editable/persisted workbench.

• [x] Regenerate OpenAPI and assert both read-only governance-metric endpoints are represented.

• [x] Copy every changed app/ backend file to deployment/app/ and verify byte parity.

Task 6: Targeted validation, browser acceptance, and local branch commit

Files:

• Test only WP11-related files and directly affected permission/architecture contracts.

• [x] Run WP11 service, API, PostgreSQL integration, frontend contract, permission, and architecture tests only.

• [x] Run Ruff only on changed Python files.

• [x] Run ESLint only on changed frontend files and run the governance metric Node model test.

• [x] Build the frontend bundle because WP11 adds a routed page.

• [x] Rebuild only the local backend/frontend services needed for WP11 browser validation.

• [x] In the browser, verify all five cards, formula/count/rate display, authorized-scope wording, state-specific detail traceability, safe detail fields, navigation, and zero console errors; verify no_data presentation through the model/API contract tests.

• [x] Confirm no ranking, employee scoring, manual metric input, trend, or analysis-development entry was introduced.

• [x] Commit the verified WP11 change on codex/dataops-phase1-equipment-governance; do not push or deploy production.