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