spec: record management report pdf staging validation gate (#451)
Records the staging validation gate for the management report PDF feature (Spec 380). Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #451
This commit is contained in:
parent
dbff2a0a90
commit
d52b674f9a
@ -0,0 +1,91 @@
|
||||
# Spec 380 Release Decision
|
||||
|
||||
Date: 2026-06-15T15:10:04+02:00
|
||||
|
||||
## Decision
|
||||
|
||||
`blocked`
|
||||
|
||||
Production Management Report PDF enablement is not approved.
|
||||
|
||||
## Reason
|
||||
|
||||
The local/repo application path passes focused tests, but Staging/Dokploy runtime controls were not executable or observable from this workspace. The deployed renderer image, internal-only network posture, service-network health, deployed env values, queue worker behavior, storage behavior, signed download behavior, OperationRun proof, audit proof, and generated PDF content smoke remain unverified.
|
||||
|
||||
## Runtime Gate
|
||||
|
||||
- Keep `TENANTPILOT_PDF_RENDERER_RUNTIME_VALIDATED=false` in Staging and Production until a later staging validation pass records `pass`.
|
||||
- Do not set `TENANTPILOT_PDF_RENDERER_RUNTIME_VALIDATED=true` in Production based only on local tests.
|
||||
- The existing `ManagementReportPdfRuntimeGate` remains the authoritative application enablement control.
|
||||
|
||||
## Evidence Summary
|
||||
|
||||
- Spec 379 focused tests: PASS, 21 tests, 173 assertions.
|
||||
- Spec 379 browser/content smoke: PASS, 1 test, 18 assertions.
|
||||
- Spec 378 renderer/gateway tests: PASS, 11 tests, 45 assertions.
|
||||
- Staging/Dokploy renderer control validation: BLOCKED, not executable from workspace.
|
||||
- Staging generation/download smoke: BLOCKED, not executable from workspace.
|
||||
- Deployment checklist update: not needed from this pass. The existing PDF Renderer Checklist already documents the required pinned image, internal URL, runtime limits, no public renderer exposure, and worker/storage considerations. The missing item is external staging evidence, not a repo checklist mismatch.
|
||||
|
||||
## Production Promotion Requirements For A Future `pass`
|
||||
|
||||
Before production promotion, a later validation pass must prove and record:
|
||||
|
||||
- Staging uses `gotenberg/gotenberg:8.34.0-chromium` or a reviewed immutable digest.
|
||||
- Gotenberg has no public port or public URL and is reachable only from the internal Dokploy/container network.
|
||||
- Deployed app/queue env uses:
|
||||
- `TENANTPILOT_PDF_RENDERER_ENABLED=true`
|
||||
- `TENANTPILOT_PDF_RENDERER_DRIVER=gotenberg`
|
||||
- internal `TENANTPILOT_PDF_RENDERER_BASE_URL`
|
||||
- explicit timeout and size limit env values
|
||||
- `TENANTPILOT_PDF_RENDERER_RUNTIME_VALIDATED=false` before the pass decision is recorded
|
||||
- Gotenberg `/health` passes from the deployed app or service network.
|
||||
- Renderer controls match the approved posture:
|
||||
- request/API timeout
|
||||
- body and output limits
|
||||
- queue and concurrency limits
|
||||
- disabled external downloads
|
||||
- disabled webhooks
|
||||
- file-only Chromium allow-list
|
||||
- private/public IP deny controls
|
||||
- correlation header
|
||||
- A ready current Review Pack generates a management PDF under an authorized operator.
|
||||
- The resulting artifact is stored privately and downloaded only through the authorized signed/server route.
|
||||
- OperationRun lifecycle, generation audit, and download audit are present with redacted metadata.
|
||||
- PDF content contains the required management-report chapters and omits forbidden raw/internal strings.
|
||||
|
||||
## Rollback Steps
|
||||
|
||||
If generation is enabled later and must be rolled back:
|
||||
|
||||
1. Set `TENANTPILOT_PDF_RENDERER_RUNTIME_VALIDATED=false`.
|
||||
2. Keep or set `TENANTPILOT_PDF_RENDERER_ENABLED=false` if the renderer service itself is unsafe or unavailable.
|
||||
3. Restart or reload web and queue workers so long-running processes stop using stale env/config.
|
||||
4. Verify the Review Pack management PDF action returns the runtime validation blocker and does not queue new generation.
|
||||
5. Monitor failed jobs, OperationRun failures, renderer health, app logs, storage write/read failures, and audit-write failures.
|
||||
6. Record post-rollback evidence before attempting re-enable.
|
||||
|
||||
## Monitoring Signals
|
||||
|
||||
Post-enable monitoring for a later pass must include:
|
||||
|
||||
- Gotenberg `/health`
|
||||
- queue depth and failed jobs on report-capable queues
|
||||
- `OperationRun` failure and blocked rates for management report generation
|
||||
- storage write/read failures on the private export disk
|
||||
- Laravel application logs for safe renderer failures
|
||||
- audit-write failures for generation and download
|
||||
- renderer response latency relative to configured request timeout and queue worker timeout
|
||||
|
||||
## Close-Out Contract
|
||||
|
||||
- Livewire v4.0+ compliance: unchanged; installed Livewire is 4.1.4 and no Livewire code changed.
|
||||
- Provider registration location: unchanged; Laravel 12 providers remain in `apps/platform/bootstrap/providers.php`.
|
||||
- Global search: no resource changed; no globally searchable resource was added or modified.
|
||||
- Destructive/high-impact actions: no new action. Existing Spec 379 `Generate management PDF` high-impact artifact action remains confirmation-, authorization-, readiness-, OperationRun-, and audit-gated.
|
||||
- Asset strategy: no assets registered or changed. Normal deployment still runs `cd apps/platform && php artisan filament:assets`.
|
||||
- Deployment impact: no migrations, env additions, queues, scheduler, storage layout, or application runtime files changed in this pass. Operationally, production remains blocked until staging validation passes.
|
||||
|
||||
## Manual Reviewer Note
|
||||
|
||||
This is an intentionally blocked release decision. The next review should verify that the committed artifacts do not overstate local tests as production proof and that `TENANTPILOT_PDF_RENDERER_RUNTIME_VALIDATED=false` remains the required gate until real Staging/Dokploy evidence exists.
|
||||
@ -0,0 +1,143 @@
|
||||
# Spec 380 Staging Runtime Validation Evidence
|
||||
|
||||
Date: 2026-06-15T15:10:04+02:00
|
||||
|
||||
## Release Gate Result
|
||||
|
||||
- Decision input: Staging/Dokploy validation for the existing Spec 379 Management Report PDF generation/download flow.
|
||||
- Result: `blocked`
|
||||
- Reason: Staging/Dokploy runtime validation was not executable from this local workspace, and no repo-contained Dokploy service definition, staging target, deployment shell, or redacted operator output was available to prove the deployed Gotenberg controls.
|
||||
- Production enablement: not approved.
|
||||
- Runtime gate: `TENANTPILOT_PDF_RENDERER_RUNTIME_VALIDATED=false` must remain in effect until a later staging validation pass proves the deployed renderer path.
|
||||
|
||||
## Baseline
|
||||
|
||||
- Branch: `380-management-report-pdf-staging-runtime-validation`
|
||||
- Starting HEAD: `dbff2a0a feat(report): implement management report pdf runtime (#450)`
|
||||
- Initial dirty state: only `specs/380-management-report-pdf-staging-runtime-validation/` was untracked.
|
||||
- Intended touched-file set:
|
||||
- `specs/380-management-report-pdf-staging-runtime-validation/artifacts/staging-runtime-validation.md`
|
||||
- `specs/380-management-report-pdf-staging-runtime-validation/artifacts/release-decision.md`
|
||||
- `specs/380-management-report-pdf-staging-runtime-validation/tasks.md`
|
||||
- Application code changes planned: none.
|
||||
- Application code changes made: none.
|
||||
- Completed-spec guardrail: Specs 378 and 379 were read as baseline context only and were not edited.
|
||||
|
||||
## Repo Baseline Verified
|
||||
|
||||
The following existing local/repo controls were verified as context, not as staging proof:
|
||||
|
||||
- `docker-compose.yml` pins the local renderer image to `gotenberg/gotenberg:8.34.0-chromium`.
|
||||
- The local `gotenberg` service has no published `ports` entry and is connected only to the Compose `sail` network.
|
||||
- The local service config includes timeout/body/concurrency controls and outbound safeguards:
|
||||
- `API_TIMEOUT`
|
||||
- `API_BODY_LIMIT`
|
||||
- `API_CORRELATION_ID_HEADER`
|
||||
- `API_DISABLE_DOWNLOAD_FROM=true`
|
||||
- `WEBHOOK_DISABLE=true`
|
||||
- `CHROMIUM_ALLOW_FILE_ACCESS_FROM_FILES=true`
|
||||
- `CHROMIUM_ALLOW_LIST=^file:///tmp/.*$`
|
||||
- `CHROMIUM_DENY_PRIVATE_IPS=true`
|
||||
- `CHROMIUM_DENY_PUBLIC_IPS=true`
|
||||
- `apps/platform/.env.example` keeps `TENANTPILOT_PDF_RENDERER_RUNTIME_VALIDATED=false`.
|
||||
- `apps/platform/config/tenantpilot.php` exposes the internal renderer base URL, driver, timeout, connect timeout, HTML/body/output size limits, and correlation header config.
|
||||
- `ManagementReportPdfRuntimeGate` blocks generation when the renderer is disabled, the driver is unsupported, or runtime validation is missing.
|
||||
- The existing management PDF generation action remains a Spec 379 high-impact artifact action with confirmation, server-side capability checks, OperationRun dispatch, and audit behavior.
|
||||
- The existing signed download route re-resolves actor, ready management PDF state, managed-environment scope, current ready Review Pack state, capability, storage existence, and download audit before returning bytes.
|
||||
|
||||
## Staging/Dokploy Runtime Controls
|
||||
|
||||
| Control | Result | Evidence / Blocker |
|
||||
|---|---|---|
|
||||
| Deployed app image/version | Blocked | No staging/Dokploy target or redacted deployment output was available in the workspace. |
|
||||
| Deployed Gotenberg image/digest | Blocked | Local Compose pins `gotenberg/gotenberg:8.34.0-chromium`; deployed image/digest was not verifiable from the app/service network. |
|
||||
| Internal-only renderer network | Blocked | Local Compose has no public port; Dokploy network posture was not observable from this workspace. |
|
||||
| App/queue internal renderer URL | Blocked | Local config defaults to `http://gotenberg:3000`; deployed `TENANTPILOT_PDF_RENDERER_BASE_URL` was not observable. |
|
||||
| Approved driver and runtime gate | Blocked | Local config supports `gotenberg` and default false runtime validation; deployed env values were not observable. |
|
||||
| Renderer `/health` from deployed network | Blocked | No command could be run inside deployed app/queue/service network. |
|
||||
| Request timeout and body/output limits | Blocked | Local config and checklist define controls; deployed env/service values were not observable. |
|
||||
| Disabled external downloads | Blocked | Local Compose sets `API_DISABLE_DOWNLOAD_FROM=true`; deployed control was not observable. |
|
||||
| Disabled webhooks | Blocked | Local Compose sets `WEBHOOK_DISABLE=true`; deployed control was not observable. |
|
||||
| File-only Chromium allow-list | Blocked | Local Compose defaults to `^file:///tmp/.*$`; deployed control was not observable. |
|
||||
| Private/public IP deny posture | Blocked | Local Compose sets Chromium and webhook deny controls; deployed control was not observable. |
|
||||
| Queue/concurrency limits | Blocked | Local Compose defines queue/concurrency env controls; deployed control was not observable. |
|
||||
| Correlation header | Blocked | Local config defaults to `Gotenberg-Trace`; deployed control was not observable. |
|
||||
|
||||
Because every deployed control remains unverified, the release gate fails closed.
|
||||
|
||||
## Existing Application Proof
|
||||
|
||||
Local focused tests were run to confirm the existing Spec 379/378 application behavior still passes in the workspace:
|
||||
|
||||
- `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec379`
|
||||
- Result: PASS, 21 tests, 173 assertions.
|
||||
- `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec379ManagementReportPdfSmokeTest.php --compact`
|
||||
- Result: PASS, 1 test, 18 assertions.
|
||||
- `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec378`
|
||||
- Result: PASS, 11 tests, 45 assertions.
|
||||
|
||||
These commands prove the current local/test application path. They do not prove Staging/Dokploy renderer service posture, deployed queue workers, production-like storage, deployed signed download behavior, or rollback.
|
||||
|
||||
## Staging Generation / Download Smoke
|
||||
|
||||
- Authorized operator generation in staging: not run.
|
||||
- OperationRun identifier: not available.
|
||||
- Private artifact storage proof: not available.
|
||||
- Authorized download response proof: not available.
|
||||
- Generation audit proof: not available.
|
||||
- Download audit proof: not available.
|
||||
- Content smoke over generated staging PDF: not available.
|
||||
|
||||
Blocked reason: no staging/Dokploy app/service-network access or redacted operator evidence was available from the implementation workspace.
|
||||
|
||||
## Content Smoke Requirements For Later Pass
|
||||
|
||||
A later pass decision must inspect a staging-generated PDF and confirm these Spec 379 baseline chapters are present:
|
||||
|
||||
- Cover
|
||||
- Executive summary
|
||||
- Governance posture
|
||||
- Key decisions
|
||||
- Top risks and findings
|
||||
- Accepted risks
|
||||
- Evidence basis
|
||||
- Limitations and disclosures
|
||||
- Next actions
|
||||
- Method summary
|
||||
|
||||
The same smoke must confirm these forbidden strings are absent:
|
||||
|
||||
- `SQLSTATE`
|
||||
- `access token`
|
||||
- `access_token`
|
||||
- `client secret`
|
||||
- `raw Graph payload`
|
||||
- `Internal MSP review`
|
||||
- `internal_msp_review`
|
||||
- serialized job markers
|
||||
- signed URLs
|
||||
|
||||
## Redaction Review
|
||||
|
||||
- Secrets included: no.
|
||||
- Signed URLs included: no.
|
||||
- Raw credentials included: no.
|
||||
- Raw provider payloads included: no.
|
||||
- Customer-sensitive payloads included: no.
|
||||
- Stack traces included: no.
|
||||
- SQL errors included: no.
|
||||
- Internal staging hostnames or private IPs included: no.
|
||||
|
||||
## Next Smallest Action
|
||||
|
||||
Run the same validation from a real Staging/Dokploy deployment context and capture redacted proof for:
|
||||
|
||||
1. deployed app image/version and env values relevant to the PDF renderer,
|
||||
2. deployed Gotenberg image tag or reviewed digest,
|
||||
3. no public renderer exposure,
|
||||
4. `/health` from app/queue/service network,
|
||||
5. renderer timeout, body/output, file allow-list, outbound deny, webhook, concurrency, and queue controls,
|
||||
6. one authorized management PDF generation and download smoke,
|
||||
7. OperationRun lifecycle, audit entries, private storage, safe headers, and PDF content smoke.
|
||||
|
||||
Until that evidence exists, production enablement remains blocked.
|
||||
@ -0,0 +1,48 @@
|
||||
# Specification Quality Checklist: Spec 380 - Management Report PDF Staging Runtime Validation & Release Hardening
|
||||
|
||||
**Purpose**: Validate specification completeness and preparation quality before implementation.
|
||||
**Created**: 2026-06-15
|
||||
**Feature**: `specs/380-management-report-pdf-staging-runtime-validation/spec.md`
|
||||
|
||||
## Candidate Selection
|
||||
|
||||
- [x] CHK001 The selected candidate is explicitly sourced from manual promotion order item 1 in `docs/product/spec-candidates.md`.
|
||||
- [x] CHK002 The user instruction "mit 380 weiter" is documented as the manual promotion decision.
|
||||
- [x] CHK003 Close alternatives are deferred instead of hidden inside the selected scope.
|
||||
- [x] CHK004 Related completed/repo-real specs are context only and not rewrite targets.
|
||||
|
||||
## Content Quality
|
||||
|
||||
- [x] CHK005 The spec states a concrete operator/release-owner problem.
|
||||
- [x] CHK006 The spec focuses on release safety and user/product trust rather than implementation novelty.
|
||||
- [x] CHK007 The smallest enterprise-capable version is bounded to staging/Dokploy validation, release decision, and rollback.
|
||||
- [x] CHK008 No `[NEEDS CLARIFICATION]` markers remain.
|
||||
- [x] CHK009 Open questions do not block safe implementation because missing staging access results in a blocked release decision.
|
||||
|
||||
## Scope Control
|
||||
|
||||
- [x] CHK010 The spec explicitly excludes new PDF features, renderer changes, delivery center scope, customer portal scope, retention/lifecycle scope, and application-code refactors by default.
|
||||
- [x] CHK011 The spec introduces no new persisted entity, table, enum/status family, operation type, abstraction, or UI framework.
|
||||
- [x] CHK012 The proportionality review is completed and supports the narrow validation scope.
|
||||
- [x] CHK013 The spec records no UI surface impact and explains why Spec 379 UI coverage remains authoritative.
|
||||
|
||||
## Architecture And Security
|
||||
|
||||
- [x] CHK014 The plan reuses existing Spec 379 runtime paths and forbids a second renderer/client/config/service.
|
||||
- [x] CHK015 The plan preserves existing RBAC, workspace/managed-environment isolation, OperationRun, audit, and private storage semantics.
|
||||
- [x] CHK016 The validation evidence must redact secrets, signed URLs, raw credentials, raw provider payloads, stack traces, SQL errors, and unnecessary customer-sensitive data.
|
||||
- [x] CHK017 The runtime gate remains fail-closed when validation is missing, blocked, or failed.
|
||||
|
||||
## Test And Release Readiness
|
||||
|
||||
- [x] CHK018 Existing Spec 379/378 tests and browser/content smoke are named as validation commands.
|
||||
- [x] CHK019 Staging/Dokploy deployment smoke is required because local tests cannot prove deployed renderer controls.
|
||||
- [x] CHK020 Rollback, monitoring, and queue-worker reload considerations are required before production enablement.
|
||||
- [x] CHK021 The tasks are ordered, small, and verifiable.
|
||||
- [x] CHK022 The tasks include final artifact hygiene checks and completed-spec modification guardrails.
|
||||
|
||||
## Review Outcome
|
||||
|
||||
- [x] CHK023 Review outcome class: `acceptable-special-case`.
|
||||
- [x] CHK024 Workflow outcome: `keep`.
|
||||
- [x] CHK025 Next command readiness: `/spec-kit-implementation-loop` after manual artifact review, with no application implementation performed during preparation.
|
||||
@ -0,0 +1,214 @@
|
||||
# Implementation Plan: Spec 380 - Management Report PDF Staging Runtime Validation & Release Hardening
|
||||
|
||||
**Branch**: `380-management-report-pdf-staging-runtime-validation` | **Date**: 2026-06-15 | **Spec**: `specs/380-management-report-pdf-staging-runtime-validation/spec.md`
|
||||
**Input**: Feature specification from `specs/380-management-report-pdf-staging-runtime-validation/spec.md`
|
||||
|
||||
## Summary
|
||||
|
||||
Validate and release-harden the already implemented Management Report PDF runtime from Spec 379. This plan does not add report features or new runtime abstractions. It produces a staging/Dokploy validation evidence artifact, a `pass` or `blocked` release decision, and rollback/monitoring instructions. The existing runtime gate remains disabled unless deployed validation passes.
|
||||
|
||||
## Technical Context
|
||||
|
||||
**Language/Version**: PHP 8.4.15, Laravel 12.52.0
|
||||
**Primary Dependencies**: Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1, PostgreSQL, existing Gotenberg 8 Chromium internal renderer service from Spec 378/379
|
||||
**Storage**: Existing private storage and `StoredReport` artifact substrate only; no new schema planned
|
||||
**Testing**: Existing Pest Unit/Feature, Filament/Livewire, Browser/content smoke, and manual/deployment validation
|
||||
**Validation Lanes**: fast-feedback, browser, deployment/staging smoke
|
||||
**Target Platform**: Laravel Sail locally; Dokploy-first Staging/Production containers
|
||||
**Project Type**: Laravel monolith with Filament admin/system panels
|
||||
**Performance Goals**: One staging generation/download smoke must record elapsed runtime and compare it against configured renderer timeout, job timeout, and worker timeout baselines; this spec adds no CI lane beyond existing Spec 379/378 focused tests and one staging smoke
|
||||
**Constraints**: no application-code change by default; no public renderer exposure; no secrets in artifacts; fail closed when validation is missing; do not rewrite Specs 378/379
|
||||
**Scale/Scope**: One existing management-report PDF generation path, one staging validation evidence package, one release decision
|
||||
|
||||
## UI / Surface Guardrail Plan
|
||||
|
||||
- **Guardrail scope**: no operator-facing surface change.
|
||||
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: existing Spec 379 generation/download surfaces are validation targets only.
|
||||
- **No-impact class, if applicable**: deployment/release-validation only.
|
||||
- **Native vs custom classification summary**: N/A.
|
||||
- **Shared-family relevance**: report generation, OperationRun, audit, storage validation only.
|
||||
- **State layers in scope**: deployment env/runtime gate; no page/shell/detail state changes.
|
||||
- **Audience modes in scope**: release owner and platform operator; existing customer-facing PDF content is only smoke-validated.
|
||||
- **Decision/diagnostic/raw hierarchy plan**: release decision first, redacted validation evidence second, raw external logs omitted or summarized safely.
|
||||
- **Raw/support gating plan**: no raw secrets, signed URLs, raw payloads, stack traces, or provider data in committed artifacts.
|
||||
- **One-primary-action / duplicate-truth control**: one release decision: `pass` or `blocked`. Failed controls are recorded as blocker reasons, not as a third release state. Do not repeat Spec 379 implementation close-out.
|
||||
- **Handling modes by drift class or surface**: hard-stop for public renderer exposure, widened URL fetching, missing runtime gate, missing audit proof, missing storage proof, or secret leakage in evidence.
|
||||
- **Repository-signal treatment**: review-mandatory if deployment checklist diverges from staging controls; follow-up-spec if structural runtime changes are needed.
|
||||
- **Special surface test profiles**: release/deployment smoke over existing high-impact artifact action.
|
||||
- **Required tests or manual smoke**: existing Spec 379 focused tests, existing Spec 379 browser/content smoke, staging runtime health, staging generation/download smoke.
|
||||
- **Exception path and spread control**: none.
|
||||
- **Active feature PR close-out entry**: Runtime Validation / Release Gate.
|
||||
- **UI/Productization coverage decision**: No UI surface impact; existing Spec 379 UI coverage remains authoritative.
|
||||
- **Screenshot or page-report need**: optional screenshot/log excerpt only if safe and redacted; PDF content smoke evidence is required.
|
||||
|
||||
## Constitution Check
|
||||
|
||||
- **Inventory-first, Snapshots-second**: PASS. Existing generated report/artifact truth remains Spec 379 truth; this spec adds only release evidence.
|
||||
- **Read/Write Separation by Default**: PASS. No Intune/provider write action. Report generation is high-impact artifact creation and remains gated by existing confirmation/authorization/audit behavior.
|
||||
- **Single Contract Path to Graph**: PASS. No Graph calls are introduced.
|
||||
- **Deterministic Capabilities**: PASS. Existing capability behavior remains unchanged.
|
||||
- **Proportionality First / No Premature Abstraction**: PASS. No new abstraction, table, enum, operation type, renderer, or framework.
|
||||
- **No New Persisted Truth Without Source-of-Truth Need**: PASS. No application persistence is planned.
|
||||
- **No New State Without Behavioral Consequence**: PASS. Release decision is spec-local validation evidence, not product runtime state.
|
||||
- **UI/Productization Coverage**: PASS. No UI surface impact is explicitly recorded.
|
||||
- **Test Suite Governance**: PASS. Reuses focused existing tests and one staging/deployment smoke; no broad lane expansion.
|
||||
- **Workspace/Tenant Isolation**: PASS. Existing Spec 379 entitlement checks are validation targets and remain unchanged.
|
||||
- **Release Safety**: PASS. Staging validation is the mandatory production gate; rollback steps are required before enablement.
|
||||
|
||||
## Existing Repository Surfaces
|
||||
|
||||
Read-only context and validation targets:
|
||||
|
||||
- `specs/378-management-report-pdf-v1/`
|
||||
- `specs/379-management-report-pdf-runtime/`
|
||||
- `specs/379-management-report-pdf-runtime/artifacts/runtime-validation.md`
|
||||
- `docs/deployment-checklist.md`
|
||||
- `docs/product/roadmap.md`
|
||||
- `docs/product/spec-candidates.md`
|
||||
- `docs/product/implementation-ledger.md`
|
||||
- `docker-compose.yml`
|
||||
- `apps/platform/config/tenantpilot.php`
|
||||
- `apps/platform/app/Support/ReviewPacks/ManagementReportPdfRuntimeGate.php`
|
||||
- `apps/platform/app/Services/ReviewPacks/ManagementReportPdfService.php`
|
||||
- `apps/platform/app/Jobs/GenerateManagementReportPdfJob.php`
|
||||
- `apps/platform/app/Http/Controllers/ManagementReportPdfDownloadController.php`
|
||||
- `apps/platform/app/Models/StoredReport.php`
|
||||
- `apps/platform/app/Filament/Resources/ReviewPackResource/Pages/ViewReviewPack.php`
|
||||
- `apps/platform/tests/Feature/ReviewPack/Spec379ManagementReportPdfTest.php`
|
||||
- `apps/platform/tests/Browser/Spec379ManagementReportPdfSmokeTest.php`
|
||||
- `apps/platform/tests/Unit/Pdf/Spec378PdfRenderingGatewayTest.php`
|
||||
|
||||
Expected write surfaces during later implementation:
|
||||
|
||||
- `specs/380-management-report-pdf-staging-runtime-validation/artifacts/staging-runtime-validation.md`
|
||||
- `specs/380-management-report-pdf-staging-runtime-validation/artifacts/release-decision.md`
|
||||
- `docs/deployment-checklist.md` only if staging validation finds a documentation mismatch
|
||||
|
||||
No application code write surface is planned.
|
||||
|
||||
## Technical Approach
|
||||
|
||||
1. Reconfirm current repo truth and completed-spec guardrails.
|
||||
2. Create a spec-local staging validation evidence artifact template during implementation.
|
||||
3. Validate the deployed Gotenberg/Dokploy runtime controls:
|
||||
- pinned image or reviewed digest
|
||||
- no public port or public URL
|
||||
- internal service URL from app/queue network
|
||||
- `/health` result from deployed context
|
||||
- request/API timeout, body/output/concurrency controls
|
||||
- disabled external downloads/webhooks
|
||||
- file-only Chromium allow-list
|
||||
- private/public IP deny controls
|
||||
4. Run existing focused application tests locally or through the project validation lane where available.
|
||||
5. Run a staging smoke over the existing Spec 379 generation/download path.
|
||||
6. Record one release decision:
|
||||
- `pass`: staging proves generation, private storage, authorized download, OperationRun, audit, and content safety.
|
||||
- `blocked`: validation could not run, external access was unavailable, or a concrete control failed; gate remains disabled and the next action is named.
|
||||
7. Record rollback and monitoring steps before any production enablement recommendation.
|
||||
|
||||
## Domain / Model Implications
|
||||
|
||||
- No new domain model.
|
||||
- No new database table, column, migration, enum, status family, operation type, or persisted release-state entity.
|
||||
- Existing `StoredReport`, `OperationRun`, `AuditLog`, and private storage behavior are observed, not changed.
|
||||
|
||||
## UI / Filament Implications
|
||||
|
||||
- No Filament resource/page/action changes are planned.
|
||||
- Existing Spec 379 action and download UI remain validation targets.
|
||||
- Livewire v4.0+ compliance remains unchanged; installed Livewire is 4.1.4.
|
||||
- Laravel 12 panel providers remain in `apps/platform/bootstrap/providers.php`; no provider registration change.
|
||||
- No globally searchable resource is added or changed. `StoredReportResource` global search posture remains unchanged from Spec 379.
|
||||
- Existing high-impact `Generate management PDF` action retains Spec 379 confirmation, authorization, readiness, OperationRun, audit, and tests.
|
||||
- No new assets are registered. Deployment still includes the normal `cd apps/platform && php artisan filament:assets` build step from the deployment checklist.
|
||||
|
||||
## OperationRun / Monitoring Implications
|
||||
|
||||
- Existing Spec 379 OperationRun type and lifecycle behavior are smoke-validated.
|
||||
- Validation evidence must distinguish:
|
||||
- renderer unavailable
|
||||
- runtime validation missing
|
||||
- generation failed
|
||||
- storage failed
|
||||
- download authorization failed
|
||||
- audit missing
|
||||
- Monitoring guidance must include queue worker health, failed jobs, renderer health, app logs, OperationRun failures, and storage write/read failures.
|
||||
|
||||
## RBAC / Policy Implications
|
||||
|
||||
- No RBAC or policy change.
|
||||
- Staging smoke must use an authorized operator for generation and verify existing view entitlement for download.
|
||||
- Existing wrong-workspace/wrong-environment protection is covered by Spec 379 tests and should be rerun or referenced in validation evidence.
|
||||
|
||||
## Audit / Evidence Implications
|
||||
|
||||
- The implementation must create redacted release evidence under the Spec 380 package.
|
||||
- Existing generation and download audit events must be observed in staging smoke.
|
||||
- Evidence must not include secrets, signed URLs, raw credentials, raw provider payloads, raw customer data, stack traces, or SQL errors.
|
||||
|
||||
## Data / Migration Implications
|
||||
|
||||
- No schema changes are planned.
|
||||
- No PostgreSQL lane is required unless a later spec update introduces a database change, which this plan does not recommend.
|
||||
|
||||
## Test Strategy
|
||||
|
||||
Required validation during implementation:
|
||||
|
||||
- `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec379`
|
||||
- `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec379ManagementReportPdfSmokeTest.php --compact`
|
||||
- `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec378`
|
||||
- `git diff --check`
|
||||
- Staging/Dokploy runtime validation checklist recorded in `artifacts/staging-runtime-validation.md`
|
||||
- Staging generation/download smoke recorded in `artifacts/release-decision.md`
|
||||
|
||||
If local Sail is unavailable, record the blocker and run the closest available project command through `./scripts/platform-sail` or the staging environment.
|
||||
|
||||
## Rollout Considerations
|
||||
|
||||
- Staging must pass before Production.
|
||||
- Do not set `TENANTPILOT_PDF_RENDERER_RUNTIME_VALIDATED=true` in Production until the staging evidence artifact says `pass`.
|
||||
- Production must match the validated controls: image/digest, internal URL, health, limits, queue/process separation, storage persistence, and no public renderer exposure.
|
||||
- Queue workers may need restart/reload after env/config changes.
|
||||
- Rollback is setting the runtime gate false, restarting/reloading workers if required, and verifying the existing action returns the runtime validation blocker.
|
||||
- No migration, scheduler, or storage layout change is planned.
|
||||
|
||||
## Risk Controls
|
||||
|
||||
- Fail closed when validation is incomplete.
|
||||
- Keep `TENANTPILOT_PDF_RENDERER_RUNTIME_VALIDATED=false` when evidence is missing.
|
||||
- Treat external Dokploy changes as operational steps, not repo code.
|
||||
- Redact evidence before commit.
|
||||
- Stop and update spec/plan before any application-code fix is attempted.
|
||||
- Do not alter completed Spec 378/379 history.
|
||||
|
||||
## Implementation Phases
|
||||
|
||||
### Phase 1 - Baseline Guardrail Reconfirmation
|
||||
|
||||
Re-read Specs 378/379, current roadmap/candidate/ledger notes, deployment checklist, and current runtime gate code. Confirm no application files need changes for the planned validation.
|
||||
|
||||
### Phase 2 - Staging Runtime Control Validation
|
||||
|
||||
Validate Gotenberg/Dokploy controls from the deployed network context and record pass/fail/block evidence.
|
||||
|
||||
### Phase 3 - Existing Workflow Staging Smoke
|
||||
|
||||
Run the existing Spec 379 generation/download path in staging and confirm artifact, OperationRun, audit, and content safety.
|
||||
|
||||
### Phase 4 - Release Decision And Rollback
|
||||
|
||||
Record `pass` or `blocked`; document promotion requirements, monitoring checks, and rollback.
|
||||
|
||||
### Phase 5 - Final Artifact Review
|
||||
|
||||
Run `git diff --check`, scan for secrets/placeholders, and ensure only allowed prep/release artifacts changed unless the spec was updated first.
|
||||
|
||||
## Filament v5 Output Contract For Implementation Close-Out
|
||||
|
||||
- **Livewire v4.0+ compliance**: unchanged; Livewire 4.1.4 is installed and no Livewire code change is planned.
|
||||
- **Provider registration location**: unchanged; Laravel 12 panel providers remain in `apps/platform/bootstrap/providers.php`.
|
||||
- **Global search**: no resource is added or changed; existing global-search decisions remain unchanged.
|
||||
- **Destructive/high-impact actions**: no new action. Existing Spec 379 high-impact artifact action remains confirmation-, authorization-, readiness-, audit-, and OperationRun-gated.
|
||||
- **Asset strategy**: no new assets; normal deployment still runs `php artisan filament:assets`.
|
||||
- **Testing plan**: rerun existing Spec 379/378 tests and staging smoke; no new test family by default.
|
||||
@ -0,0 +1,336 @@
|
||||
# Feature Specification: Spec 380 - Management Report PDF Staging Runtime Validation & Release Hardening
|
||||
|
||||
**Feature Branch**: `380-management-report-pdf-staging-runtime-validation`
|
||||
**Created**: 2026-06-15
|
||||
**Status**: Draft / Ready for implementation preparation review
|
||||
**Input**: User request: "mit 380 weiter" after explicit note that the active auto-prep queue is empty. This is treated as manual promotion of the first manual follow-through candidate in `docs/product/spec-candidates.md`: `management-report-pdf-staging-runtime-validation`.
|
||||
|
||||
## Repo-Truth Adjustment
|
||||
|
||||
Spec 379 is repo-real on `platform-dev` at commit `dbff2a0a feat(report): implement management report pdf runtime (#450)`. The current code and artifacts already provide the Management Report PDF generation/download/audit path, but production-style runtime enablement remains gated:
|
||||
|
||||
- `TENANTPILOT_PDF_RENDERER_RUNTIME_VALIDATED=false` is the default.
|
||||
- `tenantpilot.pdf_renderer.runtime_validated` and `ManagementReportPdfRuntimeGate` block generation until deployed Gotenberg validation passes.
|
||||
- `specs/379-management-report-pdf-runtime/artifacts/runtime-validation.md` records local runtime evidence and explicitly states that Staging/Dokploy validation was not executable from the local workspace.
|
||||
- `docs/product/roadmap.md`, `docs/product/spec-candidates.md`, and `docs/product/implementation-ledger.md` all identify Management Report PDF staging/Dokploy runtime validation as the remaining P1 release gap.
|
||||
|
||||
Spec 380 must not reopen Spec 378 or Spec 379 implementation history. It owns only the release-validation package: verify deployed renderer controls, record `pass` or `blocked` evidence, keep generation disabled when evidence is missing, and define the smallest safe staging-to-production promotion gate.
|
||||
|
||||
## Spec Candidate Check *(mandatory - SPEC-GATE-001)*
|
||||
|
||||
- **Problem**: Management Report PDF generation is implemented but still not productized for production because the deployed Gotenberg/Dokploy renderer path has not been validated.
|
||||
- **Today's failure**: The repo can prove local/test behavior, but the product cannot honestly claim production-ready PDF generation while the deployed renderer service, network isolation, runtime limits, queue behavior, storage behavior, and rollback path remain unverified.
|
||||
- **User-visible improvement**: Operators and release owners get a clear release gate: generation either remains blocked with exact evidence, or staging proves that management PDFs can be generated, stored, downloaded, audited, and rolled back under the approved renderer controls.
|
||||
- **Smallest enterprise-capable version**: Validate the existing Spec 379 Management Report PDF flow in Staging/Dokploy, record evidence, keep the runtime gate disabled if validation is incomplete, and document the exact promotion and rollback steps. No new PDF feature scope is included.
|
||||
- **Explicit non-goals**: No new report type, no new PDF renderer, no new Gotenberg service, no renderer package change, no customer portal, no scheduled delivery, no email/Teams delivery, no retention/lifecycle framework, no UI redesign, no new persisted entity, no new operation type, no application-code refactor by default.
|
||||
- **Permanent complexity imported**: One spec-local validation evidence artifact during implementation, one release decision record, and possibly a small deployment-checklist clarification if staging evidence exposes a documentation gap. No new runtime abstraction, table, enum, or status family is planned.
|
||||
- **Why now**: The roadmap labels this as the top post-Spec-379 P1 gap. Enabling PDF generation without deployed renderer proof would create false production confidence around a customer-facing governance artifact.
|
||||
- **Why not local**: Local tests cannot prove Dokploy networking, container isolation, renderer health, runtime limits, production-like storage, queue workers, signed download behavior, or rollback under the deployed runtime.
|
||||
- **Approval class**: Core Enterprise.
|
||||
- **Red flags triggered**: Release/runtime validation for an implemented feature, customer-facing artifact production, and external runtime dependency. Defense: this spec adds no product feature or framework; it narrows the gap to evidence, release gate, and rollback.
|
||||
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 2 | Produktnaehe: 2 | Wiederverwendung: 1 | **Gesamt: 11/12**
|
||||
- **Decision**: approve as manual-promoted Spec 380 release-validation follow-through.
|
||||
|
||||
## Candidate Selection Gate
|
||||
|
||||
- **Selected candidate**: `management-report-pdf-staging-runtime-validation`
|
||||
- **Source**: `docs/product/spec-candidates.md` manual promotion order item 1 and `docs/product/roadmap.md` current productization priority item 1.
|
||||
- **Why selected**: The user explicitly instructed to continue with 380. The top manual candidate is the highest-priority open P1 release gap and has a narrow scope over existing Spec 379 runtime truth.
|
||||
- **Roadmap relationship**: Supports the current "Management Report PDF runtime validation and release hardening" priority and keeps management-ready PDF output from being overstated before deployed renderer proof exists.
|
||||
- **Close alternatives deferred**:
|
||||
- `governance-artifact-lifecycle-retention-runtime`: deferred because artifact lifecycle/retention is broader P2 product semantics and should not be hidden inside PDF runtime validation.
|
||||
- `provider-readiness-onboarding-productization`: deferred because it is optional P2 UX friction work and unrelated to the current PDF release gate.
|
||||
- `cross-domain-indicator-runtime-follow-through`: deferred because it is a cross-surface semantics adoption lane, not a release blocker for PDF enablement.
|
||||
- `manual-system-panel-browser-fixture-or-audit-procedure`: deferred because it is validation follow-up, but not the top management-report sellability gate.
|
||||
- `first-governed-ai-runtime-consumer`: deferred P3 until core productization lanes are stable.
|
||||
- **Completed-spec guardrail result**:
|
||||
- `specs/378-management-report-pdf-v1/` is historical renderer/governance baseline context and must not be rewritten.
|
||||
- `specs/379-management-report-pdf-runtime/` is current repo-real implementation context with completed local/test evidence and an explicit open staging/Dokploy validation gap. It must not be converted back to preparation state.
|
||||
- Related completed specs such as `356`, `357`, `366`, and `377` remain context only.
|
||||
- No `specs/380-*` package existed before this preparation run.
|
||||
- **Smallest viable implementation slice**: Produce a staging/Dokploy validation evidence record for the existing Spec 379 flow and a `pass` or `blocked` release decision that keeps `TENANTPILOT_PDF_RENDERER_RUNTIME_VALIDATED=false` unless validation passes.
|
||||
- **Gate result**: PASS, based on explicit manual promotion by the user and the bounded P1 release-validation scope.
|
||||
|
||||
## Problem Statement
|
||||
|
||||
TenantPilot can now generate Management Report PDFs in repo-tested conditions, but the deployed renderer runtime has not been validated. Without a release gate, operators could enable generation in staging or production while the renderer is publicly exposed, misconfigured, missing health checks, unable to access uploaded HTML safely, writing artifacts incorrectly, or failing in a way that produces misleading OperationRun/audit states.
|
||||
|
||||
## Business / Product Value
|
||||
|
||||
- Prevents false "PDF is production-ready" claims before the deployed renderer path is proven.
|
||||
- Makes the management-report PDF feature sellable only after staging evidence exists.
|
||||
- Gives release owners a concrete `pass` or `blocked` decision instead of scattered notes across Spec 378 and Spec 379.
|
||||
- Protects customer-facing report output from renderer misconfiguration, public exposure, missing storage, or unsafe rollback.
|
||||
|
||||
## Primary Users / Operators
|
||||
|
||||
- Release owner validating Staging before Production promotion.
|
||||
- Platform operator maintaining Dokploy services, queues, storage, and env vars.
|
||||
- MSP operator who will generate customer-facing management PDFs after the runtime gate is enabled.
|
||||
- Support/platform operator diagnosing blocked or failed PDF generation.
|
||||
|
||||
## Spec Scope Fields *(mandatory)*
|
||||
|
||||
- **Scope**: deployment/release validation over the existing workspace + managed-environment Management Report PDF flow.
|
||||
- **Primary Routes**:
|
||||
- Existing Review Pack detail/action route used by Spec 379.
|
||||
- Existing Management Report PDF download route/controller from Spec 379.
|
||||
- Existing OperationRun detail route used for generation proof.
|
||||
- Existing `/up` app health route and Gotenberg `/health` internal service endpoint.
|
||||
- **Data Ownership**: No new persisted data model. Existing generated PDF artifacts remain `StoredReport`/private storage truth from Spec 379. Spec 380 implementation may create spec-local Markdown evidence under `specs/380-.../artifacts/`.
|
||||
- **RBAC**: No RBAC change. Existing Spec 379 authorization remains authoritative: generation requires the existing Review Pack / Environment Review management capability path, download requires view entitlement, and wrong workspace/environment remains deny-as-not-found.
|
||||
|
||||
For canonical-view specs:
|
||||
|
||||
- **Default filter behavior when tenant-context is active**: Not applicable. Spec 380 validates an existing source-bound report generation flow and must not introduce hidden tenant/environment context.
|
||||
- **Explicit entitlement checks preventing cross-tenant leakage**: Existing Spec 379 tests and staging smoke must confirm source-bound generation/download still re-resolve workspace and managed-environment entitlement before exposing artifact bytes.
|
||||
|
||||
## UI Surface Impact *(mandatory - UI-COV-001)*
|
||||
|
||||
Does this spec add, remove, rename, or materially change any reachable UI surface?
|
||||
|
||||
- [x] No UI surface impact
|
||||
- [ ] Existing page changed
|
||||
- [ ] New page/route added
|
||||
- [ ] Navigation changed
|
||||
- [ ] Filament panel/provider surface changed
|
||||
- [ ] New modal/drawer/wizard/action added
|
||||
- [ ] New table/form/state added
|
||||
- [ ] Customer-facing surface changed
|
||||
- [ ] Dangerous action changed
|
||||
- [ ] Status/evidence/review presentation changed
|
||||
- [ ] Workspace/environment context presentation changed
|
||||
|
||||
## UI/Productization Coverage
|
||||
|
||||
N/A - no reachable UI surface impact. Spec 379 already introduced and tested the operator action, download route, generated PDF content, and UI coverage decisions. Spec 380 may enable the existing action in a validated deployment environment through environment configuration only; it does not add, rename, or materially redesign a page, route, modal, action, table, or navigation entry.
|
||||
|
||||
## Cross-Cutting / Shared Pattern Reuse
|
||||
|
||||
- **Cross-cutting feature?**: yes, as validation over existing report generation, OperationRun, audit, storage, and deployment runtime paths.
|
||||
- **Interaction class(es)**: report generation, artifact download, runtime readiness, OperationRun proof, audit evidence, deployment gate.
|
||||
- **Systems touched**: existing PDF renderer gateway/runtime, Review Pack management PDF generation, private storage, queue workers, OperationRun, audit logs, deployment checklist.
|
||||
- **Existing pattern(s) to extend**: Spec 379 Management Report PDF flow, Spec 378 Gotenberg controls, deployment checklist, OperationRun/audit proof.
|
||||
- **Shared contract / presenter / builder / renderer to reuse**: Existing `PdfRenderingGateway`, `PdfRendererClient`, `ManagementReportPdfRuntimeGate`, `ManagementReportPdfService`, `GenerateManagementReportPdfJob`, `OperationRunService`, and audit patterns.
|
||||
- **Why the existing shared path is sufficient or insufficient**: Existing runtime paths are sufficient for generation; the missing piece is deployed-environment evidence and promotion/rollback decisioning.
|
||||
- **Allowed deviation and why**: none. A new renderer, runtime client, storage model, OperationRun type, or UI surface is out of scope.
|
||||
- **Consistency impact**: Release evidence must not contradict Spec 379 runtime gate truth; if validation is absent or failed, the gate remains disabled.
|
||||
- **Review focus**: no public renderer port, no widened URL allow-list, no secrets in evidence, no enabling production without staging pass, no completed-spec rewrites.
|
||||
|
||||
## OperationRun UX Impact
|
||||
|
||||
- **Touches OperationRun start/completion/link UX?**: no new UX semantics. Existing Spec 379 OperationRun behavior is validation target only.
|
||||
- **Shared OperationRun UX contract/layer reused**: existing Spec 379 contract.
|
||||
- **Delegated start/completion UX behaviors**: existing queued/running/succeeded/blocked and failed behavior must be observed during staging smoke.
|
||||
- **Local surface-owned behavior that remains**: N/A.
|
||||
- **Queued DB-notification policy**: unchanged.
|
||||
- **Terminal notification path**: unchanged.
|
||||
- **Exception required?**: none.
|
||||
|
||||
## Provider Boundary / Platform Core Check
|
||||
|
||||
- **Shared provider/platform boundary touched?**: no Graph/provider boundary change.
|
||||
- **Boundary classification**: platform-core deployment/runtime validation for an internal renderer service.
|
||||
- **Seams affected**: deployment env vars, renderer service network posture, queue/storage behavior, release decision evidence.
|
||||
- **Neutral platform terms preserved or introduced**: management report, renderer runtime, generated artifact, operation, release gate, rollback.
|
||||
- **Provider-specific semantics retained and why**: none beyond existing report content already governed by Spec 379 disclosure rules.
|
||||
- **Why this does not deepen provider coupling accidentally**: validation uses existing stored review/report truth and internal Gotenberg service only; no Microsoft Graph calls are introduced.
|
||||
- **Follow-up path**: Artifact lifecycle/retention remains a separate manual candidate, not part of this runtime validation spec.
|
||||
|
||||
## UI / Surface Guardrail Impact
|
||||
|
||||
| Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / N/A Note |
|
||||
|---|---|---|---|---|---|---|
|
||||
| Spec 380 release validation | no | N/A | report generation validation only | deployment/runtime gate | no | Existing UI from Spec 379 only |
|
||||
|
||||
## Decision-First Surface Role
|
||||
|
||||
N/A - no operator-facing surface change.
|
||||
|
||||
## Audience-Aware Disclosure
|
||||
|
||||
N/A - no new detail or status surface. Existing customer-facing PDF disclosure remains governed by Spec 379.
|
||||
|
||||
## UI/UX Surface Classification
|
||||
|
||||
N/A - no operator-facing list, detail, queue, audit, config, or report surface is added or materially changed.
|
||||
|
||||
## Operator Surface Contract
|
||||
|
||||
N/A - no new operator-facing page or material page refactor.
|
||||
|
||||
## Proportionality Review *(mandatory when structural complexity is introduced)*
|
||||
|
||||
- **New source of truth?**: no runtime product truth. Spec-local validation evidence is release evidence only.
|
||||
- **New persisted entity/table/artifact?**: no application persisted entity/table/artifact. Implementation may create spec-local Markdown evidence.
|
||||
- **New abstraction?**: no.
|
||||
- **New enum/state/reason family?**: no.
|
||||
- **New cross-domain UI framework/taxonomy?**: no.
|
||||
- **Current operator problem**: release owners need proof before enabling customer-facing PDF generation in deployed environments.
|
||||
- **Existing structure is insufficient because**: Spec 379 proves local/test behavior but explicitly cannot prove Staging/Dokploy runtime controls from the local workspace.
|
||||
- **Narrowest correct implementation**: validate the deployed runtime, record `pass` or `blocked` evidence, keep the runtime gate disabled until proof exists, and document rollback.
|
||||
- **Ownership cost**: one evidence artifact and release checklist upkeep.
|
||||
- **Alternative intentionally rejected**: immediately enabling the runtime flag based on local tests only.
|
||||
- **Release truth**: current-release truth; not future-release preparation.
|
||||
|
||||
### Compatibility posture
|
||||
|
||||
This feature assumes a pre-production environment. No compatibility shim, legacy alias, dual-write, migration fallback, or historical fixture is planned.
|
||||
|
||||
## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)*
|
||||
|
||||
- **Test purpose / classification**: Feature, Browser/content smoke, deployment smoke, and release-validation evidence over existing code.
|
||||
- **Validation lane(s)**: fast-feedback for existing focused tests, browser for existing Spec 379 smoke, manual/deployment validation for Dokploy runtime.
|
||||
- **Why this classification and these lanes are sufficient**: Existing tests prove application behavior; staging smoke proves the deployed service, queue, storage, health, and env gate path that local tests cannot prove.
|
||||
- **New or expanded test families**: none by default. If staging validation reveals a repo-code mismatch, implementation must update the active spec before adding tests or code beyond release artifacts.
|
||||
- **Fixture / helper cost impact**: none by default; reuse the existing Spec 379 test/staging fixture.
|
||||
- **Heavy-family visibility / justification**: one existing browser/content smoke is reused because the output is a customer-facing PDF artifact.
|
||||
- **Special surface test profile**: release/deployment smoke over existing high-impact artifact action.
|
||||
- **Standard-native relief or required special coverage**: no new Filament surface; existing Spec 379 coverage remains authoritative.
|
||||
- **Reviewer handoff**: confirm lane fit, no new runtime abstractions, no application code drift, no secrets in evidence, and exact `pass` or `blocked` release decision.
|
||||
- **Budget / baseline / trend impact**: no test-suite expansion expected; staging smoke runtime must record elapsed seconds and compare them with configured renderer, job, and worker timeout baselines if it approaches or exceeds any configured limit.
|
||||
- **Escalation needed**: document-in-feature if validation is blocked or fails; follow-up-spec only if structural deployment/runtime changes are required.
|
||||
- **Active feature PR close-out entry**: Runtime Validation / Release Gate.
|
||||
- **Planned validation commands**:
|
||||
- `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec379`
|
||||
- `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec379ManagementReportPdfSmokeTest.php --compact`
|
||||
- `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec378`
|
||||
- `git diff --check`
|
||||
- Staging/Dokploy renderer health and generation/download smoke commands recorded in the implementation evidence artifact.
|
||||
|
||||
## User Scenarios & Testing *(mandatory)*
|
||||
|
||||
### User Story 1 - Validate deployed PDF runtime before enablement (Priority: P1)
|
||||
|
||||
As a release owner, I need proof that the Staging/Dokploy Gotenberg runtime is internal, healthy, pinned, bounded, and usable by the Laravel app/queue containers before I enable Management Report PDF generation outside local/test contexts.
|
||||
|
||||
**Why this priority**: This is the direct production-safety blocker named by roadmap and Spec 379 evidence.
|
||||
|
||||
**Independent Test**: Run the staging validation checklist and confirm the evidence artifact records the deployed image, internal-only network posture, health check result, env controls, successful queued generation, private storage, signed/server-authorized download, OperationRun proof, audit proof, and content-leakage smoke.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** a deployed staging environment with the approved Gotenberg service, **When** the release owner runs validation, **Then** the artifact records the pinned image, no public port, health status, configured limits, and internal service URL with secrets redacted.
|
||||
2. **Given** a ready Review Pack source in staging, **When** the existing generation action runs under a permitted operator, **Then** the PDF is generated, stored privately, downloadable only through the authorized path, linked to an OperationRun, and audited.
|
||||
3. **Given** generated PDF content, **When** the smoke check inspects it, **Then** required management-report sections exist and forbidden raw/internal strings are absent.
|
||||
|
||||
### User Story 2 - Keep generation blocked when validation is missing or failed (Priority: P1)
|
||||
|
||||
As a platform operator, I need generation to remain disabled when runtime validation is incomplete or failed, so that customers do not receive artifacts from an untrusted renderer path.
|
||||
|
||||
**Why this priority**: A blocked state is safer than a false positive release decision.
|
||||
|
||||
**Independent Test**: With missing or failed staging evidence, verify `TENANTPILOT_PDF_RENDERER_RUNTIME_VALIDATED` remains false and the existing UI/action state reports the runtime validation blocker instead of queueing generation.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** the staging renderer cannot be reached or controls do not match the approved posture, **When** validation completes, **Then** the release decision is `blocked` and the runtime gate remains disabled.
|
||||
2. **Given** validation is blocked by unavailable external access, **When** the implementation closes, **Then** the artifact states exactly what was not validated and no production enablement is recommended.
|
||||
|
||||
### User Story 3 - Promote with rollback and monitoring instructions (Priority: P2)
|
||||
|
||||
As a release owner, I need exact promotion, rollback, and monitoring steps so that staging success can be applied safely and reversed quickly if generation fails after enablement.
|
||||
|
||||
**Why this priority**: Release hardening is incomplete without a reversible enablement path.
|
||||
|
||||
**Independent Test**: Review the release decision artifact and confirm it names env vars, queue restart requirements, storage checks, OperationRun/audit checks, rollback steps, and monitoring signals.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** staging validation passes, **When** the release owner prepares production promotion, **Then** the artifact lists the required production env vars and controls without exposing secrets.
|
||||
2. **Given** a post-enable failure occurs, **When** rollback is needed, **Then** the documented path disables the runtime gate, restarts/reloads workers if required, and verifies no new generation can start.
|
||||
|
||||
## Functional Requirements *(mandatory)*
|
||||
|
||||
- **FR-380-001**: The implementation MUST verify the deployed Gotenberg image is pinned to the approved Gotenberg 8 Chromium image or reviewed digest.
|
||||
- **FR-380-002**: The implementation MUST verify the renderer is internal-network only and has no public port or public URL exposure.
|
||||
- **FR-380-003**: The implementation MUST verify Gotenberg `/health` from the deployed application or service network, not only from a developer workstation.
|
||||
- **FR-380-004**: The implementation MUST verify renderer limits and safety controls: request timeout, body/output limits, concurrency/queue controls, disabled external downloads, disabled webhooks, file-only Chromium allow-list, and private/public IP deny posture unless a later approved spec changes those controls.
|
||||
- **FR-380-005**: The implementation MUST verify Laravel staging env/config uses the internal renderer base URL, approved driver, explicit timeouts/limits, and a false runtime gate until validation passes.
|
||||
- **FR-380-006**: The implementation MUST exercise the existing Spec 379 generation/download flow in staging using a ready current Review Pack source and an authorized operator.
|
||||
- **FR-380-007**: The staging smoke MUST verify OperationRun lifecycle proof, private artifact storage, authorized download, generation audit, and download audit.
|
||||
- **FR-380-008**: The staging content smoke MUST verify required management-report chapters are present and forbidden raw/internal strings are absent. The Spec 379 baseline chapters are Cover, Executive summary, Governance posture, Key decisions, Top risks and findings, Accepted risks, Evidence basis, Limitations and disclosures, Next actions, and Method summary; forbidden examples include SQLSTATE, access token/access_token, client secret, raw Graph payload, Internal MSP review/internal_msp_review, serialized job markers, and signed URLs.
|
||||
- **FR-380-009**: The validation evidence artifact MUST redact secrets, signed URLs, raw credentials, raw provider payloads, stack traces, and internal customer data not needed for the release decision.
|
||||
- **FR-380-010**: If validation is incomplete, blocked, or finds any failed control, the runtime gate MUST remain disabled and the release decision MUST be `blocked`.
|
||||
- **FR-380-011**: If validation passes, the release decision MUST document the exact env/config controls required for production promotion and the monitoring checks to run after enablement.
|
||||
- **FR-380-012**: The rollback path MUST include disabling the runtime gate, restarting or reloading relevant workers if needed, verifying blocked action state, and recording post-rollback evidence.
|
||||
- **FR-380-013**: Spec 380 MUST NOT modify Spec 378 or Spec 379 historical artifacts, completed task markers, validation notes, or close-out history.
|
||||
- **FR-380-014**: Spec 380 MUST NOT introduce new report features, new renderer infrastructure, new persisted entities, new operation types, or new UI surfaces unless the spec is updated and reapproved before implementation.
|
||||
|
||||
## Non-Functional Requirements
|
||||
|
||||
- **NFR-380-001**: Validation must be evidence-first and must not rely on undocumented operator memory.
|
||||
- **NFR-380-002**: Release evidence must be safe to commit to the repo without secrets or sensitive tenant payloads.
|
||||
- **NFR-380-003**: The validation path must fail closed.
|
||||
- **NFR-380-004**: Production enablement must remain behind Staging validation.
|
||||
- **NFR-380-005**: Queue, storage, and audit observations must be concrete enough for a reviewer to distinguish "runtime unavailable" from "application generation bug".
|
||||
- **NFR-380-006**: No Microsoft Graph/provider calls may be introduced by validation or report rendering.
|
||||
- **NFR-380-007**: Existing Filament v5 / Livewire v4 compliance remains unchanged; no Livewire v3 APIs may be introduced.
|
||||
|
||||
## Data / Truth-Source Requirements
|
||||
|
||||
- Runtime validation truth for this release lives in the Spec 380 evidence artifact produced during implementation.
|
||||
- Product runtime truth remains existing `StoredReport`, `OperationRun`, `AuditLog`, private storage, and Spec 379 generation/download state.
|
||||
- Environment truth lives in Staging/Dokploy env vars and service configuration; committed artifacts must summarize the relevant controls without secrets.
|
||||
- The runtime gate is the authoritative enablement control. A generated PDF in local/test does not prove production readiness.
|
||||
|
||||
## Edge Cases
|
||||
|
||||
- Staging/Dokploy access is unavailable from the implementation workspace.
|
||||
- Gotenberg health passes but HTML conversion fails because the file allow-list is too narrow or too broad.
|
||||
- Renderer service is healthy but app/queue containers cannot resolve the internal hostname.
|
||||
- Generation succeeds but storage write or download authorization fails.
|
||||
- OperationRun succeeds but audit evidence is missing.
|
||||
- Staging pass exists but production env differs from staging.
|
||||
- Rollback disables the web env but stale queue workers still hold old env/config.
|
||||
|
||||
## Out Of Scope
|
||||
|
||||
- New Management Report PDF product features.
|
||||
- Technical Evidence Report, Auditor Evidence Report, scheduled delivery, email/Teams delivery, delivery center, public links, or customer portal.
|
||||
- Artifact lifecycle, retention, legal hold, export bundles, deletion semantics, or customer self-serve report packaging.
|
||||
- Renderer replacement, additional renderer package, browser runtime in Laravel containers, or package governance redo.
|
||||
- Application code changes unless validation proves a bounded repo-code mismatch and the spec/plan are updated first.
|
||||
- Changes to completed Specs 378/379 or their validation history.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- **AC-380-001**: A committed Spec 380 evidence artifact records Staging/Dokploy validation pass or block with date, environment, deployed image, controls checked, commands/actions run, and redacted results.
|
||||
- **AC-380-002**: When validation is blocked or failed, the artifact states that `TENANTPILOT_PDF_RENDERER_RUNTIME_VALIDATED` remains false and production enablement is not approved.
|
||||
- **AC-380-003**: When validation passes, the artifact states exactly which controls passed and which env/config values must be present before production promotion.
|
||||
- **AC-380-004**: Existing focused Spec 379 and Spec 378 tests are run or any inability to run them is recorded with reason.
|
||||
- **AC-380-005**: Staging smoke proves generation, private storage, authorized download, OperationRun proof, and audit proof, or records the exact blocker.
|
||||
- **AC-380-006**: Rollback instructions are present and include worker/config reload considerations.
|
||||
- **AC-380-007**: No application code, migrations, models, services, jobs, Filament resources, routes, tests, or runtime behavior are changed during preparation.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Staging validation produces a clear `pass` or `blocked` decision in one implementation pass.
|
||||
- A reviewer can decide whether production enablement is allowed without reading Specs 378/379 end to end.
|
||||
- If blocked, generation remains fail-closed and the next smallest action is obvious.
|
||||
- If passed, production promotion has concrete env, queue, storage, monitoring, and rollback steps.
|
||||
|
||||
## Risks
|
||||
|
||||
- Staging/Dokploy access may be unavailable from the implementation environment; mitigation is to record a blocked release decision and keep generation disabled.
|
||||
- Staging may not match production sufficiently; mitigation is to require production controls to match the validated staging controls before enablement.
|
||||
- Evidence artifacts may accidentally include secrets; mitigation is to require redaction and reviewer check before commit.
|
||||
- Runtime enablement may require external Dokploy changes that are not represented in the repo; mitigation is to document them explicitly as operational steps, not hidden code changes.
|
||||
|
||||
## Assumptions
|
||||
|
||||
- The user instruction "mit 380 weiter" is an explicit manual promotion decision for the next numbered spec.
|
||||
- Spec 379 code and tests are the current implementation baseline and should not be duplicated or reopened.
|
||||
- Staging/Dokploy validation may require operator access outside the local workspace.
|
||||
- Production remains gated until Staging validation passes.
|
||||
|
||||
## Open Questions
|
||||
|
||||
None blocking preparation. The only external dependency is access to Staging/Dokploy during the later implementation/validation pass; lack of access results in a blocked release decision, not invented implementation scope.
|
||||
|
||||
## Follow-up Spec Candidates
|
||||
|
||||
- Governance Artifact Lifecycle & Retention runtime.
|
||||
- Management report delivery packaging or scheduled delivery.
|
||||
- Auditor/technical evidence report profiles.
|
||||
- Customer portal report consumption.
|
||||
@ -0,0 +1,105 @@
|
||||
# Tasks: Spec 380 - Management Report PDF Staging Runtime Validation & Release Hardening
|
||||
|
||||
**Input**: `specs/380-management-report-pdf-staging-runtime-validation/spec.md`, `specs/380-management-report-pdf-staging-runtime-validation/plan.md`
|
||||
**Prerequisites**: Spec and plan are complete. Spec 378 and Spec 379 are read-only historical/repo-real context. This spec does not implement new report features or application runtime changes by default.
|
||||
**Tests**: Reuse existing focused Spec 379/378 tests, existing Spec 379 browser/content smoke, and staging/Dokploy validation evidence.
|
||||
|
||||
## Test Governance Checklist
|
||||
|
||||
- [x] Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
|
||||
- [x] Existing tests stay in the smallest honest family and no new heavy/browser family is introduced by default.
|
||||
- [x] Shared helpers, factories, seeds, fixtures, and context defaults are not widened.
|
||||
- [x] Planned validation commands cover existing report generation behavior plus deployed runtime controls.
|
||||
- [x] The release/deployment smoke profile is explicit.
|
||||
- [x] Any blocked validation or failed-control staging evidence is recorded in the active spec artifact, not hidden in terminal output.
|
||||
|
||||
## Phase 1: Baseline And Guardrail Reconfirmation
|
||||
|
||||
**Purpose**: Confirm the repo baseline and protect completed-spec history before release validation.
|
||||
|
||||
- [x] T001 Create `specs/380-management-report-pdf-staging-runtime-validation/artifacts/staging-runtime-validation.md` and record branch, HEAD, dirty state, current date, and intended touched-file set.
|
||||
- [x] T002 Re-read `specs/378-management-report-pdf-v1/spec.md`, `specs/378-management-report-pdf-v1/plan.md`, `specs/378-management-report-pdf-v1/tasks.md`, and renderer artifacts without editing Spec 378.
|
||||
- [x] T003 Re-read `specs/379-management-report-pdf-runtime/spec.md`, `specs/379-management-report-pdf-runtime/plan.md`, `specs/379-management-report-pdf-runtime/tasks.md`, and `specs/379-management-report-pdf-runtime/artifacts/runtime-validation.md` without editing Spec 379.
|
||||
- [x] T004 [P] Verify current runtime gate code paths in `apps/platform/config/tenantpilot.php` and `apps/platform/app/Support/ReviewPacks/ManagementReportPdfRuntimeGate.php`.
|
||||
- [x] T005 [P] Verify current generation/download paths in `apps/platform/app/Services/ReviewPacks/ManagementReportPdfService.php`, `apps/platform/app/Jobs/GenerateManagementReportPdfJob.php`, and `apps/platform/app/Http/Controllers/ManagementReportPdfDownloadController.php`.
|
||||
- [x] T006 [P] Verify current artifact and owner-surface paths in `apps/platform/app/Models/StoredReport.php` and `apps/platform/app/Filament/Resources/ReviewPackResource/Pages/ViewReviewPack.php`.
|
||||
- [x] T007 Confirm no application code, migration, model, service, job, policy, Filament resource, route, view, or test change is planned; if a code change appears necessary, stop and update spec/plan before continuing.
|
||||
|
||||
## Phase 2: Staging/Dokploy Runtime Control Validation
|
||||
|
||||
**Purpose**: Prove the deployed renderer runtime controls before enabling generation outside local/test contexts.
|
||||
|
||||
- [x] T008 Complete the runtime-control sections in `specs/380-management-report-pdf-staging-runtime-validation/artifacts/staging-runtime-validation.md` for environment, deployed app image/version, Gotenberg image/digest, service network posture, env controls, health result, blockers, and redaction review.
|
||||
- [ ] T009 Validate the deployed Gotenberg image is pinned to `gotenberg/gotenberg:8.34.0-chromium` or a reviewed immutable digest, and record the result in `specs/380-management-report-pdf-staging-runtime-validation/artifacts/staging-runtime-validation.md`. *(Blocked in this pass: no Staging/Dokploy deployment context or redacted operator output was available.)*
|
||||
- [ ] T010 Validate the deployed Gotenberg service has no public port or public URL exposure and is reachable only from the internal Dokploy/container network. *(Blocked in this pass: no Staging/Dokploy deployment context or redacted operator output was available.)*
|
||||
- [ ] T011 Validate the app/queue runtime uses the internal `TENANTPILOT_PDF_RENDERER_BASE_URL`, approved `gotenberg` driver, explicit timeouts, configured size limits, and `TENANTPILOT_PDF_RENDERER_RUNTIME_VALIDATED=false` before a pass decision is recorded. *(Blocked in this pass: no Staging/Dokploy deployment context or redacted operator output was available.)*
|
||||
- [ ] T012 Validate Gotenberg `/health` from the deployed app or service network and record status, timestamp, and redacted command/output summary. *(Blocked in this pass: no Staging/Dokploy deployment context or redacted operator output was available.)*
|
||||
- [ ] T013 Validate renderer safety controls: request/API timeout, disabled external downloads, disabled webhooks, file-only Chromium allow-list, private/public IP deny controls, body/output limits, queue/concurrency limits, and correlation header. *(Blocked in this pass: no Staging/Dokploy deployment context or redacted operator output was available.)*
|
||||
- [x] T014 If any control is missing, widened, inaccessible, or unverifiable, record the blocker in `specs/380-management-report-pdf-staging-runtime-validation/artifacts/staging-runtime-validation.md`; unless a later successful validation resolves it, the release decision must be `blocked` and `TENANTPILOT_PDF_RENDERER_RUNTIME_VALIDATED=false` must remain in effect.
|
||||
|
||||
## Phase 3: Existing Application Proof
|
||||
|
||||
**Purpose**: Re-run focused existing tests and prove the deployed generation flow.
|
||||
|
||||
- [x] T015 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec379` or record why the command could not run.
|
||||
- [x] T016 Run `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec379ManagementReportPdfSmokeTest.php --compact` or record why the command could not run.
|
||||
- [x] T017 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec378` or record why the command could not run.
|
||||
- [ ] T018 In staging, use an authorized operator and a ready current Review Pack source to run the existing Management Report PDF generation action. *(Blocked in this pass: no Staging/Dokploy deployment context or authorized operator path was available.)*
|
||||
- [ ] T019 Verify the staging generation creates the expected OperationRun lifecycle evidence and record the operation identifier in redacted form in `specs/380-management-report-pdf-staging-runtime-validation/artifacts/staging-runtime-validation.md`. *(Blocked in this pass: no staging generation was executable.)*
|
||||
- [ ] T020 Verify the staging generation stores the PDF as a private artifact and does not expose public storage paths or signed URLs in committed evidence. *(Blocked in this pass: no staging generation was executable.)*
|
||||
- [ ] T021 Verify the staging download route re-authorizes access and returns safe PDF response headers. *(Blocked in this pass: no staging download was executable.)*
|
||||
- [ ] T022 Verify generation and download audit entries exist with redacted metadata and no secrets, signed URLs, raw provider payloads, stack traces, or SQL errors. *(Blocked in this pass: no staging generation/download was executable.)*
|
||||
- [ ] T023 Verify content smoke over the generated PDF includes the Spec 379 baseline chapters (Cover, Executive summary, Governance posture, Key decisions, Top risks and findings, Accepted risks, Evidence basis, Limitations and disclosures, Next actions, Method summary) and excludes forbidden raw/internal strings including SQLSTATE, access token/access_token, client secret, raw Graph payload, Internal MSP review/internal_msp_review, serialized job markers, and signed URLs. *(Blocked in this pass: no staging PDF artifact was generated.)*
|
||||
|
||||
## Phase 4: Release Decision, Monitoring, And Rollback
|
||||
|
||||
**Purpose**: Convert validation evidence into a clear `pass` or `blocked` release gate.
|
||||
|
||||
- [x] T024 Create `specs/380-management-report-pdf-staging-runtime-validation/artifacts/release-decision.md` with exactly one decision: `pass` or `blocked`.
|
||||
- [ ] T025 If the decision is `pass`, document the required production env vars and controls before any production promotion, including renderer base URL, runtime gate, timeouts, limits, queue worker reload, storage persistence, and monitoring checks. *(N/A in this pass because the release decision is `blocked`; future pass requirements are recorded in `artifacts/release-decision.md`.)*
|
||||
- [x] T026 If the decision is `blocked`, document the smallest next action and explicitly state that production enablement is not approved.
|
||||
- [x] T027 Document rollback steps in `specs/380-management-report-pdf-staging-runtime-validation/artifacts/release-decision.md`: set `TENANTPILOT_PDF_RENDERER_RUNTIME_VALIDATED=false`, restart/reload queue workers if required, verify action blocked state, and monitor failed jobs/OperationRuns.
|
||||
- [x] T028 Update `docs/deployment-checklist.md` only if staging validation proves the existing PDF renderer checklist is inaccurate or incomplete; otherwise record no docs update needed in the release decision artifact.
|
||||
- [x] T029 Record monitoring signals for post-enable observation: renderer health, queue depth/failures, OperationRun failure rate, storage write/read failures, app logs, and audit-write failures.
|
||||
|
||||
## Phase 5: Final Validation And Artifact Hygiene
|
||||
|
||||
**Purpose**: Ensure this remains release-validation work, not hidden application implementation.
|
||||
|
||||
- [x] T030 Run `git diff --check`.
|
||||
- [x] T031 Scan Spec 380 artifacts for secrets, signed URLs, raw credentials, raw provider payloads, customer-sensitive payloads, stack traces, and SQL errors; redact before commit.
|
||||
- [x] T032 Confirm `specs/378-management-report-pdf-v1/` and `specs/379-management-report-pdf-runtime/` were not modified.
|
||||
- [x] T033 Confirm no application runtime files changed unless the spec/plan were updated first to authorize a bounded fix.
|
||||
- [x] T034 Complete the implementation close-out with Livewire v4 compliance, provider registration location, global-search status, high-impact action status, asset strategy, validation commands, and deployment impact.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- [x] NT001 Do not add a new report type, delivery center, schedule, email/Teams delivery, public link, customer portal, or auditor/technical report.
|
||||
- [x] NT002 Do not add a second PDF renderer, package, Gotenberg service, browser runtime, PDF client, or renderer config.
|
||||
- [x] NT003 Do not add migrations, models, persisted entities, operation types, enum/status families, or framework abstractions.
|
||||
- [x] NT004 Do not change Filament resources/pages/actions, Livewire components, routes, views, policies, jobs, services, or tests by default.
|
||||
- [x] NT005 Do not rewrite completed Specs 378/379 or remove close-out, validation, smoke, or completed-task history.
|
||||
- [x] NT006 Do not enable production generation unless staging validation passes and the release decision is `pass`.
|
||||
|
||||
## Dependencies And Ordering
|
||||
|
||||
- Phase 1 must complete before any staging validation.
|
||||
- Phase 2 controls must pass before a `pass` release decision is possible.
|
||||
- Phase 3 application proof must pass before a `pass` release decision is possible.
|
||||
- Phase 4 records promotion/rollback only after Phase 2 and Phase 3 outcomes are known.
|
||||
- Phase 5 runs last.
|
||||
|
||||
## Parallel Opportunities
|
||||
|
||||
- T004, T005, and T006 can run in parallel.
|
||||
- T009 through T013 can be checked in parallel when the operator has Dokploy/service access.
|
||||
- T015, T016, and T017 can run in parallel if the local Sail/browser environment supports it.
|
||||
|
||||
## Implementation Strategy
|
||||
|
||||
1. Treat Spec 379 as the implementation baseline.
|
||||
2. Validate deployment controls before feature enablement.
|
||||
3. Exercise the existing PDF generation path in staging.
|
||||
4. Record a clear `pass` or `blocked` release decision.
|
||||
5. Keep production disabled unless evidence is strong.
|
||||
6. Stop and respec before any application-code remediation.
|
||||
Loading…
Reference in New Issue
Block a user