TenantAtlas/specs/101-golden-master-baseline-governance-v1/plan.md

#+#+#+#+

Implementation Plan: Golden Master / Baseline Governance v1 (R1.1–R1.4)

Branch: 101-golden-master-baseline-governance-v1 | Date: 2026-02-19 | Spec: spec.md Input: Feature specification from spec.md

Summary

Implement a workspace-owned Golden Master baseline that can be captured from a tenant into an immutable snapshot, assigned to tenants, and compared (“Soll vs Ist”) to generate drift findings + a compact operational summary.

This feature reuses existing patterns:

• tenant-scoped OperationRun for capture/compare observability + idempotency
• findings for drift tracking with sha256 fingerprints

Technical Context

Language/Version: PHP 8.4.x Framework: Laravel 12 Admin UI: Filament v5 (requires Livewire v4.0+) Storage: PostgreSQL (Sail locally); SQLite is used in some tests Testing: Pest v4 (vendor/bin/sail artisan test) Target Platform: Docker via Laravel Sail (macOS dev) Project Type: Laravel monolith (server-rendered Filament + Livewire) Performance Goals:

• Compare completes within ~2 minutes for typical tenants (≤ 500 in-scope policies) Constraints:
• Baseline/monitoring pages must be DB-only at render time (no outbound HTTP)
• Operation start surfaces enqueue-only (no remote work inline) Scale/Scope:
• Multi-tenant, workspace isolation is an authorization boundary

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

• Inventory-first: compare operates on “last observed” inventory/policy versions; baseline snapshot is an explicit immutable capture.
• Read/write separation: capture/compare are operational jobs; any mutations are confirmed, audited, and tested.
• Graph contract path: no Graph calls on UI surfaces; any Graph usage (if introduced) must go through GraphClientInterface and config/graph_contracts.php.
• Deterministic capabilities: new baseline capabilities are added to the canonical registry and role maps.
• RBAC-UX semantics: non-member is 404; member but missing capability is 403.
• Run observability: capture/compare are always OperationRun-tracked; start surfaces only create/reuse runs and enqueue work.
• Data minimization: workspace-owned baseline snapshots are minimized and must not store tenant secrets.
• Badge semantics (BADGE-001): finding severity/status uses existing BadgeCatalog mapping.
• Filament Action Surface Contract: resources/pages created or modified must define Header/Row/Bulk/Empty-State + inspect affordance.

✅ Phase 0 and Phase 1 design choices satisfy the constitution. No violations are required.

Project Structure

Documentation (this feature)

specs/101-golden-master-baseline-governance-v1/
├── plan.md
├── spec.md
├── research.md
├── data-model.md
├── quickstart.md
└── contracts/
   └── baseline-governance.openapi.yaml

Source Code (repository root)

app/
├── Filament/
├── Jobs/
├── Models/
├── Policies/
├── Services/
└── Support/

database/
└── migrations/

resources/
└── views/

tests/
├── Feature/
└── Unit/

Structure Decision: Implement baseline governance as standard Laravel models, migrations, services, jobs, and Filament resources/pages under the existing app/ conventions.

Phase 0 — Research (completed)

Outputs:

• research.md

Key decisions captured:

• Workspace-owned, data-minimized baseline snapshots (reusable across tenants)
• OperationRun types baseline_capture and baseline_compare using ensureRunWithIdentity() for idempotent starts
• Precondition failures return 422 with stable reason_code and do not create runs
• Findings reuse findings with sha256 fingerprints; Phase 2 adds findings.source to satisfy source = baseline.compare

Phase 1 — Design & Contracts (completed)

Outputs:

• data-model.md
• contracts/baseline-governance.openapi.yaml
• quickstart.md

UI Surfaces (Filament v5)

• Workspace-context: Governance → Baselines
  • Resource for baseline profile CRUD
  • Capture action (manage capability)
  • Tenant assignment management (manage capability)
• Tenant-context: “Soll vs Ist” landing page
  • Compare-now action (view capability)
  • Links to latest compare run + findings

Authorization & capabilities

• Add new workspace capabilities:
  • workspace_baselines.view
  • workspace_baselines.manage
• Enforce membership as 404; capability denial as 403.

Operation types

• baseline_capture (tenant = source tenant)
• baseline_compare (tenant = target/current tenant)

Agent context update (completed)

The agent context update script was run during planning. It should be re-run after this plan update if the automation depends on parsed plan values.

Phase 2 — Execution Plan (to be translated into tasks.md)

1. Migrations + models

• Add baseline tables (baseline_profiles, baseline_snapshots, baseline_snapshot_items, baseline_tenant_assignments)
• Add findings.source column + index to meet FR-015

2. Services

• Baseline scope resolution (profile scope ∩ assignment override)
• Snapshot identity calculation and dedupe strategy
• Compare engine to produce drift items and severity mapping (FR-009)

3. Jobs (queued)

• CaptureBaselineSnapshotJob (creates snapshot, items, updates active snapshot when applicable)
• CompareBaselineToTenantJob (creates/updates findings + writes run summary_counts)

4. Filament UI

• Baseline profiles resource (list/view/edit) with action surfaces per spec matrix
• Tenant assignment UI surface (v1: single baseline per tenant)
• “Soll vs Ist” tenant landing page and dashboard card action

5. RBAC + policies

• Capability registry + role maps + UI enforcement
• Regression tests for 404 vs 403 semantics

6. Tests (Pest)

• CRUD authorization + action surface expectations
• Capture snapshot dedupe
• Compare finding fingerprint idempotency
• Precondition failures return 422 and create no OperationRun

7. Formatting

• Run vendor/bin/sail bin pint --dirty

Complexity Tracking

None.