TenantAtlas/specs/355-platform-sellable-smoke-matrix/repo-truth-map.md

# Repo Truth Map: Spec 355 - Platform Sellable Smoke Matrix

Status: implementation complete / browser-verified  
Branch: `355-platform-sellable-smoke-matrix`  
Date: 2026-06-05  
Baseline commit before prep branch: `a9c54205` (`feat: finding exceptions accepted risk resolution guidance v1 (spec 354) (#425)`)

## Branch And Working-Tree Safety

- Starting branch before prep: `platform-dev`
- Initial `git status --short --branch`: clean
- Initial `git diff --stat`: empty
- Spec Kit branch created via repo script:
  - `.specify/scripts/bash/create-new-feature.sh --json --short-name 'platform-sellable-smoke-matrix' --number 355 'Platform Sellable Smoke Matrix'`
- Current branch after setup: `355-platform-sellable-smoke-matrix`
- Current uncommitted change before writing prep artifacts: only `specs/355-platform-sellable-smoke-matrix/`

## Why 355 Was Selected

- The user provided Spec 355 directly, so this is not an auto-selected backlog refresh.
- Specs 351-354 already productized the main operator-guidance lanes, but they did so one surface at a time.
- The next honest question is integrated sellability, not another isolated feature:
  - Does the first blocker make sense?
  - Does the next action stay dominant?
  - Does scope continuity survive the click?
  - Are customer-safe boundaries still truthful?
  - Do evidence and proof surfaces support trust instead of pulling the operator into diagnostics-first detail?

## Why Close Alternatives Were Deferred

- Spec 356 (`Review Pack PDF/HTML Renderer v1`) depends on the underlying operator/productization flow being coherent first.
- Spec 357 (`Customer Portal Boundary Contract`) should not be promoted before customer-safe boundary truth is proven inside the current operator surfaces.
- Spec 358 (`Private AI Resolution Suggestion Foundation`) is intentionally later than human-guided workflow stability.
- Spec 359 (`Localization v1`) is a likely follow-up if this matrix exposes mixed-language or dominant-copy gaps, but it should not hide workflow incoherence.
- Spec 360 (`Portfolio / Cross-Tenant Action Readiness`) is broader than the current single-platform sellable gate.

## Completed-Spec Guardrail Result

| Related spec | Current repo signal | Guardrail handling for Spec 355 |
|---|---|---|
| Spec 351 - Review Output Resolve Actions v1 | commit `d4e4d2d1`, checked implementation tasks, residual P2 browser notes, spec header still `Draft` | runtime context only; do not normalize or silently erase historical findings |
| Spec 352 - Environment Dashboard Operator Guidance Consolidation | commit `9a564d6b`, repo-truth says implemented | direct dependency; use as the dashboard baseline |
| Spec 353 - Provider Connections Resolution Guidance v1 | commit `d2876af9`, spec says implemented with close-out audit pending | runtime context only; use committed behavior, not checklist wording, as truth |
| Spec 354 - Finding Exceptions / Accepted Risk Resolution Guidance v1 | commit `a9c54205`, checked tasks, screenshots, browser smoke test file exists, spec header still `Draft` | direct dependency; verify named blocker conditions explicitly before final readiness verdict |

No completed spec package is being normalized back into preparation-only wording.

## Dependency Gate Verification

Spec 355's own draft required:

- Specs 351-354 closed/committed
- Spec 354 patched, browser-verified, and free of specific open P1/P2 findings around:
  - accepted-risk state priority
  - approval queue scope continuity
  - dominant guidance localization
  - fake/inert recommended action semantics

The implementation-phase verification completed this gate:

- accepted-risk state priority: verified in browser on expired and expiring focused queue states
- approval queue scope continuity: verified from Governance Inbox into the focused accepted-risk lane with preserved back-link context
- dominant guidance localization: initially failed in the German focused queue lane because `FindingRiskGovernanceResolver` returned hardcoded English warning copy; fixed in-scope and re-verified
- fake or inert recommended action semantics: not observed in the tested flows

Result:

- implementation proceeded legitimately
- final readiness language is no longer blocked by the Spec 354 dependency gate

## Primary Runtime Surfaces

| Surface | Repo truth | Why it matters to Spec 355 |
|---|---|---|
| `EnvironmentDashboard` | environment-owned command surface with implemented top guidance from Spec 352 | starting point for first-blocker coherence |
| `ProviderConnectionResource` | workspace provider hub with implemented guidance from Spec 353 | provider-owner destination for dashboard blocker routing |
| `EnvironmentRequiredPermissions` | environment-bound provider-readiness surface with implemented guidance from Spec 353 | verifies decision-first provider blocker explanation |
| `CustomerReviewWorkspace` | workspace review hub with implemented review-output guidance and action mapping from Spec 351 | owner surface for review-output blocker resolution |
| `ViewEnvironmentReview` | review-owner detail surface | verifies no duplicate CTA rails and customer-safe boundary discipline |
| `FindingExceptionsQueue` | workspace accepted-risk queue with implemented guidance from Spec 354 | owner surface for accepted-risk follow-up |
| `ViewFindingException` | accepted-risk lifecycle detail | verifies accepted-risk guidance continuity and action safety |
| `GovernanceInbox` | workspace-wide operator queue with existing productization and browser smoke history | cross-domain workbench continuity check |
| `EvidenceOverview` | workspace-wide evidence hub | verifies evidence path and calm/blocked evidence messaging |
| `ViewEvidenceSnapshot` | evidence basis detail | owner proof surface for evidence detail when review/provider flows deep-link into it |
| `OperationRunResource` / operation detail routes | workspace operation proof truth | verifies run proof and follow-up traceability |

## Existing Proof And Browser Assets

| Asset | Current repo truth |
|---|---|
| Local/testing login helper | `/admin/local/smoke-login` exists in `apps/platform/routes/web.php` |
| Review ready-path fixture helper | `tenantpilot:review-output:seed-browser-fixture` exists |
| Browser smoke for Governance Inbox | `apps/platform/tests/Browser/Spec346GovernanceInboxOperatorWorkflowSmokeTest.php` exists |
| Browser smoke for review-output actions | `apps/platform/tests/Browser/Spec351ReviewOutputResolveActionsSmokeTest.php` exists |
| Browser smoke for dashboard guidance | `apps/platform/tests/Browser/Spec352EnvironmentDashboardGuidanceSmokeTest.php` exists |
| Browser smoke for provider readiness | `apps/platform/tests/Browser/Spec353ProviderReadinessGuidanceSmokeTest.php` exists |
| Browser smoke for accepted-risk guidance | `apps/platform/tests/Browser/Spec354AcceptedRiskGuidanceSmokeTest.php` exists |
| Existing screenshots for key flows | Spec packages 351-354 already contain screenshots for dashboard, provider, review, and accepted-risk surfaces |

## Coverage Gaps That Spec 355 Should Not Hide

| Area | Repo truth | Implication |
|---|---|---|
| Evidence Overview (`UI-044`) | route-inventory entry exists, but no page report or screenshot is currently linked there | use Spec 355 artifacts first; do not claim strong durable audit history yet |
| Workspace operation detail (`UI-017`) | route-inventory entry exists, but no page report is linked there | use Spec 355 matrix/report to capture proof-path observations |
| Spec 351 close-out state | historical browser notes still mention residual P2 items | the sellable gate must verify whether those notes still reproduce |
| Spec 354 close-out shape | screenshots exist, but no spec-package browser-flow audit artifact is present | dependency gate must be runtime-verified, not assumed |

## Existing Fixture And Context Signals

| Need | Current signal |
|---|---|
| Review-output blocked flow | Spec 351 smoke history plus current runtime surface and fixture command |
| Review-output ready flow | `tenantpilot:review-output:seed-browser-fixture` exists |
| Provider blocker flow | Spec 352/353 smoke history plus current provider-readiness surfaces |
| Accepted-risk expiring / expired flow | Spec 354 runtime, screenshots, and browser smoke test exist |
| Governance Inbox item flow | Governance Inbox page and existing browser smoke exist |
| Evidence path | Evidence Overview and evidence-detail surfaces exist, but fixture richness must still be inventoried |
| Operation proof path | operation hub/detail surfaces and proof-link helpers exist, but fixture richness must still be inventoried |
| No urgent action state | dashboard/provider/review surfaces already claim calm states in neighboring specs; Spec 355 must verify a calm case still exists in current data |

## Fixture Inventory Actually Used

| Need | Verified local fixture used in Spec 355 |
|---|---|
| Dashboard provider blocker | workspace `spec-352-guidance-browser-audit`, environment `spec-352-audit-provider-blocker`, smoke-login user `smoke-requester+352@tenantpilot.local` |
| Dashboard review-output blocker | workspace `spec-352-guidance-browser-audit`, environment `spec-352-audit-review-output`, review `#31` |
| Customer Review Workspace | `environment_id=52`, draft review `#31` |
| Accepted-risk expiring / expired / incomplete | workspace `wp`, environment `spec342-demo-accepted-risks`, exceptions `#7`, `#8`, `#9` after local-only fixture augmentation |
| Governance Inbox item | workspace `wp`, environment `spec342-demo-accepted-risks` |
| Evidence incomplete | workspace `wp`, environment `spec342-demo-evidence-incomplete`, operation `#24` |
| Operation proof | workspace `wp`, environment `spec342-demo-evidence-incomplete`, operation `#24` |
| Calm no-urgent-action state | workspace `spec-352-guidance-browser-audit`, environment `spec-352-audit-no-urgent` |

## Browser Matrix Outcome

- 10 of 10 required flows were exercised in the browser
- 12 of 12 required screenshots were captured under `specs/355-platform-sellable-smoke-matrix/artifacts/screenshots/`
- no browser console errors were observed in the Playwright session
- no failing network or server responses were observed in the verified flows
- one in-scope defect was found and fixed during the run:
  - `apps/platform/app/Services/Findings/FindingRiskGovernanceResolver.php` no longer emits hardcoded English accepted-risk warning messages in the German focused queue lane

## Regression Outcome

- targeted affected Spec 354 regressions passed after the localization fix:
  - `tests/Feature/Monitoring/Spec354FindingExceptionsQueueGuidanceTest.php`
  - `tests/Feature/Findings/Spec354FindingExceptionDetailGuidanceTest.php`
  - `tests/Unit/ResolutionGuidance/Spec354AcceptedRiskResolutionAdapterTest.php`
- `./vendor/bin/sail php ./vendor/bin/pint --dirty` passed
- `git diff --check` passed
- broader `Spec351` through `Spec354` family-filter runs were attempted in Sail but were killed with exit `137`, so close-out rests on the narrower affected regressions plus browser proof

## Draft-To-Repo Corrections That Must Stay Explicit

1. Spec 355 is not a greenfield "sellable mode". It is a verification package over already-existing surfaces.
2. Evidence Overview and operation detail are real surfaces, but their durable audit/report coverage is lighter than dashboard/provider/review/risk/governance.
3. Browser proof already exists around many adjacent specs, but no current artifact ties them together into one integrated sellable-readiness call.
4. Dependency truth for Specs 351-354 is strong but not cosmetically uniform; implementation must verify real blocker closure before claiming readiness.

## Out Of Scope Confirmed By Repo Truth

- no new portal or customer-facing standalone product surface
- no PDF/HTML review-pack renderer
- no AI guidance or private AI runtime consumer
- no provider execution rewrite
- no Governance Inbox or dashboard rebuild
- no new persistence or new release-gate entity

## Actual Narrow Implementation Shape

- browser-first verification across the current owner surfaces
- spec-local matrix, report, screenshot, and fixture artifacts
- one bounded runtime fix in a pre-existing accepted-risk warning resolver
- one targeted feature-test expansion to lock the localization boundary