# Spec Candidate 384 - Evidence & Review Readiness Integration v1 ## Candidate Status Candidate for implementation after Specs 380, 381, 382, and 383. This candidate integrates the new baseline subject identity/resolution semantics into Evidence Snapshot completeness, Baseline Drift Posture, Review Output Readiness, publication blockers, and Review Pack export. ## Depends On - Spec 380 - Provider Resource Identity & Binding Foundation v1 - Spec 381 - Baseline Matching Pipeline & Canonicalization v1 - Spec 382 - Baseline Compare Result Semantics & Gap Classification v1 - Spec 383 - Baseline Subject Resolution UI & Operator Decisions v1 ## Spec Candidate Check - **Problem**: Evidence and Review readiness consume compare results that may still contain overloaded or false blocker states. - **Today's failure**: Customer-ready output can be blocked by expected provider defaults, internal limitations can be presented as hard blockers, and unsupported foundation coverage can look like missing input. - **User-visible improvement**: Evidence, reviews, and Review Packs can distinguish customer-ready, published-with-limitations, internal-only, and blocked states based on true unresolved governance risk. - **Smallest enterprise-capable version**: Update Baseline Drift Posture, Evidence Snapshot completeness mapping, Environment Review readiness, Review Pack readiness/guidance, and customer-safe limitation wording only. - **Explicit non-goals**: No new binding data model, no matching pipeline implementation, no resolution UI, no workflow engine, no new report profile architecture, no broad management report redesign, and no historical review migration. - **Permanent complexity imported**: Readiness reason mapping, limitation categories in evidence details, review/readiness gate updates, Review Pack wording changes, internal technical rendering, and cross-surface tests. - **Why now**: After Specs 380-383, the system has trustworthy subject resolution and operator decisions; customer-facing readiness must consume those semantics or continue showing false blockers. - **Why not local**: A local Review Pack label patch would leave Evidence Snapshot, Baseline Drift Posture, OperationRun guidance, and Environment Review readiness inconsistent. - **Approval class**: Core Enterprise. - **Red flags triggered**: Many surfaces touched and new readiness classifications. The defense is that all surfaces already consume baseline compare truth and must share publication safety semantics. - **Score**: Nutzen: 2 | Dringlichkeit: 1 | Scope: 1 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | **Gesamt: 9/12** - **Decision**: approve after Specs 380-383 if scope stays limited to readiness integration and customer-safe wording. ## UI Surface Impact - **Reachable surface changed/added**: yes, existing Evidence, Environment Review, Review Pack, Stored Report/Review Pack readiness labels, and OperationRun guidance may change. - **Page archetype**: readiness/status integration over existing surfaces, not a new primary workflow page. - **Design depth**: update labels, limitation summaries, blocker messaging, and internal technical appendix rules; no new layout system. - **Customer/operator safety**: customer-safe output must avoid raw provider IDs, `provider_resource_bindings`, `canonical_subject_key`, internal policy version IDs, and raw OperationRun payloads. - **Dangerous/high-impact actions**: none added; publication/readiness gate behavior changes require tests because they affect customer-ready output. ## Proportionality Review 1. **Current operator problem**: Operators cannot safely publish customer-ready review output when false blockers and limitations are mixed together. 2. **Why existing structure is insufficient**: Evidence and Review readiness currently consume overloaded compare states and cannot distinguish resolved defaults from unresolved governed blockers. 3. **Narrowest correct implementation**: Consume the new semantics in existing readiness and export paths only; no new report architecture or workflow. 4. **Ownership cost**: Evidence, Environment Review, Review Pack, OperationRun guidance, and test owners must maintain shared readiness mappings. 5. **Rejected alternative**: Review Pack-only wording was rejected because Evidence and Environment Review would still disagree about customer readiness. 6. **Current-release truth or future prep**: Current-release customer trust work because compare output already influences Evidence, Reviews, and Review Pack export. ## Problem Evidence and Review readiness currently consume baseline compare results that can contain overloaded or false blocker states. This can cause: - customer-ready output blocked by expected provider defaults, - internal limitations presented as hard blockers, - unsupported foundation coverage presented as missing input, - unresolved ambiguity not clearly separated from accepted limitations, - review packs that are too conservative or not precise enough. TenantPilot needs evidence/review integration that reflects the improved compare semantics. ## Goal Make customer readiness and publication blockers depend on real unresolved governance risk, not on expected provider defaults or accepted limitations. ## Scope ### In Scope - Update Baseline Drift Posture source consumption of new compare semantics. - Update Evidence Snapshot completeness mapping. - Update Environment Review readiness. - Update Review Pack output readiness. - Update Review Pack output resolution guidance. - Update customer-safe limitation wording. - Update internal technical detail rendering. - Add tests for blocker vs limitation behavior. - Ensure Review Pack export does not leak raw provider IDs. ### Out of Scope - New binding data model. - Matching pipeline implementation. - Operator resolution UI. - Generic workflow engine. - New report profile architecture. - Broad management report redesign. - Full historical review migration. ## Evidence Completeness Mapping Evidence should distinguish: ```text complete complete_with_limitations partial_action_required partial_limitation_only missing stale ``` If existing evaluator only supports: ```text complete partial missing stale ``` then the additional classification can live in evidence details/readiness reason payloads while preserving public enum compatibility. ## Baseline Drift Posture Rules Baseline Drift Posture must distinguish: ```text No drift found Drift found Compare blocked by unresolved ambiguity Compare partial due to unsupported limitations Compare incomplete due to missing evidence Compare failed ``` Zero findings must not be treated as missing input when compare completed successfully. ## Publication Rules ### Customer-ready Allowed when: - all required governed subjects are resolved, - no unresolved ambiguity hides real drift, - no required evidence is missing, - accepted limitations are allowed by profile/report policy, - customer-safe limitation summary is available where needed. ### Published with limitations Allowed when: - unsupported/foundation inventory-only limitations are accepted, - excluded non-governed subjects are audited, - no unresolved governed blocker remains, - limitations are disclosed in customer-safe language. ### Internal-only Required when: - unresolved ambiguity remains, - required evidence is missing, - compare cannot support customer-safe posture claim, - missing provider resource cannot be confidently interpreted, - limitation wording would be misleading externally. ### Publication blocked Required when: - unresolved governed blockers exist, - required review sections cannot be composed, - evidence basis is missing, - compare failed for required dimension, - output would imply false assurance. ## Review Pack Wording Customer-safe wording must avoid internal implementation jargon. Do not expose: ```text provider_resource_bindings canonical_subject_key raw provider IDs internal policy version IDs operation_run context payloads ``` Customer-safe examples: ```text Some baseline resources could not be verified because multiple matching resources require operator confirmation. Some foundation configuration classes are currently monitored as inventory-only and are disclosed as limitations. No drift was identified for the verified baseline scope. ``` Internal technical appendix may include more detail if the report profile allows it. ## OperationRun and Review Guidance Review guidance should produce next steps such as: ```text Resolve ambiguous baseline subjects before publication. Refresh evidence after baseline subject resolutions are applied. Accept or exclude unsupported foundation resources before creating a customer-ready pack. Re-run baseline compare after inventory sync completes. ``` It should not say: ```text Resolve review blockers ``` without explaining the real blocker class. ## Integration Points Expected areas: - `BaselineDriftPostureSource` - `EvidenceCompletenessEvaluator` - Evidence Snapshot sources - `EnvironmentReviewReadinessGate` - review composer services - `ReviewPackOutputReadiness` - `ReviewPackOutputResolutionGuidance` - Review Pack export/rendering services - Stored Report / Review Pack UI readiness labels - OperationRun follow-up support ## Acceptance Criteria - Resolved built-ins/defaults do not create review publication blockers. - Accepted limitations produce "published with limitations" where policy allows. - Unsupported foundation inventory-only coverage is not mislabeled as missing input. - Real unresolved ambiguity blocks customer-ready output. - Missing provider resource after trusted identity blocks or surfaces as drift according to semantics. - Missing local evidence is described as evidence limitation, not resource drift. - Review Pack output remains customer-safe. - Internal technical details remain available for operators. - YPTW2-like compare results can become internal-only, customer-ready, or published-with-limitations based on true unresolved state. ## Required Tests - Evidence test: resolved built-in does not make baseline drift posture partial action-required. - Evidence test: unresolved ambiguity makes posture partial action-required. - Evidence test: accepted limitation makes posture complete-with-limitations or equivalent. - Review test: publication blocker appears only for unresolved governed blocker. - Review test: accepted limitation does not block customer-ready output when report policy allows limitations. - Review test: unsupported foundation appears as limitation, not missing input. - Review Pack test: customer-safe output does not expose raw provider IDs. - Review Pack test: internal profile can include technical diagnostics. - Regression test: zero drift findings after completed compare is valid complete state. - Regression test: historical/legacy compare payload still renders safely. ## Validation Commands ```bash cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Evidence/BaselineDriftPostureSourceTest.php ``` ```bash cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/EnvironmentReview/EnvironmentReviewComposerTest.php ``` ```bash cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReviewPack/Spec349ReviewPackResolutionGuidanceTest.php ``` Add focused tests for new readiness reason mapping. ## Risks - Accidentally allowing customer-ready output with unresolved risk. - Blocking customer output for expected provider defaults. - Leaking raw provider identities in customer pack. - Creating inconsistent semantics between Evidence, Review, and Review Pack. - Producing too many limitation labels and lowering trust. ## Recommendation Implement this fifth. This candidate completes the full product loop: identity -> matching -> result semantics -> operator resolution -> evidence/review/customer-ready output.