ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

docs: reconcile decision register product truth (#361)

Browse Source 
## Summary
- add the Spec 306 docs-only reconciliation package under `specs/306-decision-register-reconciliation/`
- reconcile existing Spec 265, runtime pages/builders/tests, and product docs so Decision Register is treated as repo-verified rather than a missing greenfield feature
- minimally sync `docs/product/implementation-ledger.md`, `docs/product/roadmap.md`, and `docs/product/spec-candidates.md` to reflect current repo truth
- classify Decision Register as `partial productization`, not `not implemented`
- recommend one narrow next step instead of a broad restart: `307-decision-register-evidence-operationrun-link-polish`

## Scope
- docs-only reconciliation and product-doc truth sync
- no application runtime changes
- no migrations
- no routes, policies, providers, or UI asset changes
- no test edits

## Key Conclusions Recorded
- a broad new `Decision Register v1` or `Decision Register & Approval Workflow v1` spec should not be created
- Spec 265 runtime is repo-verified and usable on `/admin/governance/decisions`
- the remaining gap is narrow productization around direct evidence/report links, OperationRun links, and adjacent customer-safe consumption polish
- product docs previously understated repo truth and were corrected minimally in this branch

## Filament / Runtime Notes
- remains compliant with Filament v5 on Livewire v4
- no provider registration changes; provider registration location remains `apps/platform/bootstrap/providers.php`
- no globally searchable resources were added or changed in this docs-only PR
- no destructive actions were added or changed
- no asset registration changes; existing deploy posture for `cd apps/platform && php artisan filament:assets` is unchanged

## Validation Notes
- the reconciliation artifact records the focused existing test evidence used to support the product-truth claims
- no new runtime validation was executed in this turn beyond committing and pushing the docs-only package

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #361
This commit is contained in:
ahmido 2026-05-15 10:18:48 +00:00
parent f24e72269c
commit ba0b6ec07e
8 changed files with 1277 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
docs/product/implementation-ledger.md
View File

@ -4,7 +4,7 @@ # TenantPilot Implementation Ledger
> **Last reviewed:** 2026-05-12
> **Use for:** Repo-based implementation status and product-surface maturity assessment
> **Do not use for:** Roadmap priority, spec priority, or proof that tests were executed in the current branch
> **Scoped maintenance:** 2026-05-15 Tenant Panel dead-code retirement guardrail update after Spec 304; 2026-05-12 roadmap/ledger alignment after the admin workspace navigation and tenant-owned surface repair candidate intake from the repo-verified navigation/panel audit; 2026-05-06 ledger conflict cleanup plus alignment with `docs/product/roadmap.md` and `docs/product/spec-candidates.md` after the cross-domain indicator candidate intake and the current manual-promotion backlog review.
> **Scoped maintenance:** 2026-05-15 Decision Register reconciliation update after Spec 306; 2026-05-15 Tenant Panel dead-code retirement guardrail update after Spec 304; 2026-05-12 roadmap/ledger alignment after the admin workspace navigation and tenant-owned surface repair candidate intake from the repo-verified navigation/panel audit; 2026-05-06 ledger conflict cleanup plus alignment with `docs/product/roadmap.md` and `docs/product/spec-candidates.md` after the cross-domain indicator candidate intake and the current manual-promotion backlog review.
## Purpose
@ -23,7 +23,7 @@ ## Purpose
## Current Product Position
TenantPilot ist aktuell ein starkes internes Governance- und Operations-Produkt mit belastbaren Foundations fuer Execution Truth, Baselines/Drift, Findings, Evidence, Reviews, Review Packs, Supportability, Telemetry, Safety Controls und eine repo-reale governed AI policy foundation. Darauf sitzen inzwischen mehrere repo-real productization slices: eine customer-safe Review-/Governance-Package-Surface im Admin-Kontext, released-review detail handoff, compliance interpretation overlays, bounded external support-desk handoff, commercial lifecycle state handling mit read-only gating sowie eine kanonische cross-tenant compare preview mit promotion preflight. Die Repo-Wahrheit liegt damit klar ueber einer simplen Lesart von "R1 done / R2 partial" und auch ueber einer rein foundation-only Interpretation fuer Reviews, Support und Portfolio-Preparation. Gleichzeitig ist das Produkt noch nicht voll als kundenseitig konsumierbare Portfolio- und Commercial-Plattform ausgereift: Es fehlen die letzte customer-safe self-serve productization ueber der Review-Surface, actual portfolio promotion execution, ein bounded governance decision pack and approval workflow, wiederholbare Billing-/Subscription-Truth, eine klarere Stored-Reports-Surface und der erste governed AI runtime consumer ueber der bereits repo-realen AI policy foundation.
TenantPilot ist aktuell ein starkes internes Governance- und Operations-Produkt mit belastbaren Foundations fuer Execution Truth, Baselines/Drift, Findings, Evidence, Reviews, Review Packs, Supportability, Telemetry, Safety Controls und eine repo-reale governed AI policy foundation. Darauf sitzen inzwischen mehrere repo-real productization slices: eine customer-safe Review-/Governance-Package-Surface im Admin-Kontext, released-review detail handoff, compliance interpretation overlays, bounded external support-desk handoff, commercial lifecycle state handling mit read-only gating, eine kanonische cross-tenant compare preview mit promotion preflight sowie ein repo-verifizierter operatorseitiger Decision Register ueber bestehender FindingException-Decision-Truth. Die Repo-Wahrheit liegt damit klar ueber einer simplen Lesart von "R1 done / R2 partial" und auch ueber einer rein foundation-only Interpretation fuer Reviews, Support und Portfolio-Preparation. Gleichzeitig ist das Produkt noch nicht voll als kundenseitig konsumierbare Portfolio- und Commercial-Plattform ausgereift: Es fehlen die letzte customer-safe self-serve productization ueber der Review-Surface, actual portfolio promotion execution, ein schmaler Decision-Register-Proof-Link-Follow-up, wiederholbare Billing-/Subscription-Truth, eine klarere Stored-Reports-Surface und der erste governed AI runtime consumer ueber der bereits repo-realen AI policy foundation.
## Runtime Guardrails
@ -81,6 +81,7 @@ ## Implemented Capabilities
| Drift findings and governance pressure | sellable | yes | yes | repo tests, not run | yes | yes | `app/Models/Finding.php`; `app/Filament/Widgets/Dashboard/RecentDriftFindings.php`; `tests/Feature/Findings/*` |
| Findings inboxes and governance inbox | fast sellable | yes | yes | repo tests, not run | yes | yes | `app/Filament/Pages/Findings/MyFindingsInbox.php`; `app/Filament/Pages/Findings/FindingsIntakeQueue.php`; `app/Filament/Pages/Governance/GovernanceInbox.php`; `tests/Feature/Findings/MyWorkInboxTest.php`; `tests/Feature/Governance/*` |
| Finding exceptions and risk acceptance workflow | fast sellable | yes | yes | repo tests, not run | yes | yes | `app/Models/FindingException.php`; `app/Services/Findings/FindingExceptionService.php`; `app/Filament/Resources/FindingExceptionResource.php`; `tests/Feature/Findings/FindingExceptionWorkflowTest.php` |
| Decision Register operator surface | implemented but not productized | yes | yes | repo tests, run in Spec 306 | yes | no | `specs/265-decision-register-approval/spec.md`; `app/Filament/Pages/Governance/DecisionRegister.php`; `app/Support/GovernanceDecisions/GovernanceDecisionRegisterBuilder.php`; `tests/Feature/Governance/DecisionRegisterPageTest.php`; `tests/Feature/Findings/FindingExceptionDecisionRegisterNavigationTest.php` |
| Restore workflow with safety gates | sellable | yes | yes | repo tests, not run | yes | yes | `app/Models/OperationRun.php`; restore gates and tests in `tests/Feature/Restore/*` |
| Evidence snapshots | foundation-only | yes | yes | repo tests, not run | yes | no | `app/Models/EvidenceSnapshot.php`; `app/Services/Evidence/EvidenceSnapshotService.php`; `tests/Feature/Evidence/*` |
| Tenant reviews | fast sellable | yes | yes | repo tests, not run | yes | yes | `app/Models/TenantReview.php`; `app/Services/TenantReviews/TenantReviewService.php`; `tests/Feature/TenantReview/*` |
@ -129,6 +130,7 @@ ## Fast-Sellable Or Not-Yet-Productized Capabilities
- Customer-facing review consumption: Tenant Reviews, Evidence Snapshots, Review Packs, the Customer Review Workspace, the customer-safe released-review detail mode, governance-package delivery cues, compliance interpretation overlays, and commercial-lifecycle-aware access states are repo-real; broader lifecycle/governance taxonomy work remains separate.
- Findings Workflow v2: Triage, Assignment, My Work, Intake, Governance Inbox, Exceptions, notifications, and the three queue-facing cleanup/hardening follow-through packages are now repo-backed; later cross-tenant action layers remain separate work.
- Decision Register: Spec 265 operator register runtime and tests are repo-backed; direct evidence/report and OperationRun proof-link polish remains a narrow productization gap, not a Greenfield v1.
- Product scalability and self-service: Onboarding, Support, Help, Entitlements, commercial lifecycle state handling, and external support-desk handoff are repo-real; broader trial/demo and billing-subscription truth still remain.
- MSP portfolio operations: Portfolio-Triage plus cross-tenant compare preview and promotion preflight are repo-real; actual promotion execution and broader portfolio action orchestration remain open.
- Platform operations maturity: Control Tower und Ops Controls sind stark, aber einige geplante operatorseitige Drilldowns/Exports fehlen noch.
@ -138,7 +140,6 @@ ## Not Implemented
- Auditor Pack Delivery & Executive Export v1
- Cross-Tenant Promotion Execution v1
- Decision Register & Approval Workflow v1
- Governance Artifact Lifecycle & Retention v1
- Customer-Facing Localization Adoption v1
- Billing & Subscription Truth Layer v1
@ -226,7 +227,7 @@ ## Open Gaps & Blockers
| Workspace-first / ManagedEnvironment core cutover is not started | Strategic architecture blocker | The repo still centers many governance, support, and portfolio surfaces on `Tenant` semantics, so future multi-provider work would otherwise accumulate more tenant- and Microsoft-centric core coupling | Platform core / provider-neutral posture | `Workspace-first / ManagedEnvironment Core Cutover` pack in `docs/product/spec-candidates.md` (planned as Specs 279-287) |
| Auditor-ready executive export is still missing | Productization blocker | Review truth remains short of auditor-/executive-ready delivery, even though the dedicated follow-through is now spec-backed | R2 review delivery | `specs/263-auditor-pack-executive-export/spec.md` |
| Cross-tenant promotion execution is still missing | Product blocker | Compare preview and preflight are repo-real, but the actual portfolio action remains absent even though the execution package is now spec-backed | MSP Portfolio & Operations | `specs/264-cross-tenant-promotion-execution/spec.md` |
| Decision register and approval workflow is still missing | Product blocker | Decision-based operating still lacks a bounded approval-ready closure and decision-record package with audit trail | Decision-based operating | `Decision Register & Approval Workflow v1` |
| Decision Register proof-link polish is still pending | Productization gap | The operator register exists, but direct evidence/report, `OperationRun`, and review-pack proof links are not fully productized on the register path | Decision-based operating | `decision-register-evidence-operationrun-link-polish` |
| Governance-artifact lifecycle runtime is still missing | Trust / auditability blocker | Lifecycle taxonomy and point retention rules exist, but governance artifacts still lack immutable-reference, hold, export, delete, and suspended/read-only runtime semantics | Lifecycle governance / enterprise trust | `Governance Artifact Lifecycle & Retention v1` |
| Cross-domain progress and indicator semantics guardrail is still missing | UX / trust guardrail | Bars, percentages, scores, readiness, risk, usage, and generation-state hints still lack one shared taxonomy and standards layer above the OperationRun-specific rules | UI semantics / product trust | `Cross-Domain Progress / Indicator Semantics candidate group` |
| Admin workspace navigation and tenant-owned surface contract drift remains open | UX / IA repair blocker | Inventory and adjacent tenant-owned admin surfaces still conflict between workspace-home clean-sidebar rules and valid environment-bound admin access, leaving active product breaks and stale hide-first assumptions in place | UI maturity / admin runtime contract | `admin-inventory-navigation-cutover` from the `Admin Workspace Navigation & Tenant-owned Surface Repair candidate group` |
@ -242,7 +243,7 @@ ## Recommended Manual Promotions
- `Cross-Domain Progress / Indicator Semantics candidate group` -> anchored by `specs/268-operationrun-activity-feedback/spec.md`, `specs/270-operationrun-progress-contract/spec.md`, `specs/271-counted-progress-rollout/spec.md`, `specs/272-operationrun-phase-composite-progress/spec.md`, `docs/ui/tenantpilot-enterprise-ui-standards.md`, and the current progress-like UI seams called out in `docs/product/spec-candidates.md`
- `Admin Workspace Navigation & Tenant-owned Surface Repair candidate group` -> anchored by `apps/platform/app/Filament/Clusters/Inventory/InventoryCluster.php`, `apps/platform/app/Filament/Pages/InventoryCoverage.php`, `apps/platform/app/Filament/Resources/InventoryItemResource.php`, `apps/platform/app/Filament/Resources/EntraGroupResource.php`, `apps/platform/app/Filament/Concerns/WorkspaceScopedTenantRoutes.php`, `apps/platform/app/Support/OperateHub/OperateHubShell.php`, and the navigation/runtime tests called out in `docs/product/spec-candidates.md`; promote `admin-inventory-navigation-cutover` first, then keep the route audit, groups cutover, contract split, and tenant-panel dead-code retirement as separate sequenced follow-through
- `Workspace-first / ManagedEnvironment Core Cutover` pack -> anchored by `docs/product/spec-candidates.md`, `docs/product/roadmap.md`, `docs/product/implementation-ledger.md`, and the tenant-centric platform seams already visible across review, support, portfolio, and governance surfaces; keep it as a clean development-stage cutover pack rather than a compatibility-layer program
- `Decision Register & Approval Workflow v1` -> anchored by `specs/250-decision-governance-inbox/spec.md`, `specs/257-governance-decision-convergence/spec.md`, and `docs/product/roadmap.md`
- `decision-register-evidence-operationrun-link-polish` -> anchored by `specs/265-decision-register-approval/spec.md`, `specs/306-decision-register-reconciliation/decision-register-reconciliation.md`, `apps/platform/app/Filament/Pages/Governance/DecisionRegister.php`, `apps/platform/app/Support/GovernanceDecisions/GovernanceDecisionRegisterBuilder.php`, and the focused Decision Register tests
- `Governance Artifact Lifecycle & Retention v1` -> anchored by `specs/158-artifact-truth-semantics/spec.md`, `specs/262-lifecycle-governance-taxonomy/spec.md`, and `docs/product/standards/lifecycle-governance.md`
- `Billing & Subscription Truth Layer v1` -> anchored by `specs/247-plans-entitlements-billing-readiness/spec.md` and `specs/251-commercial-entitlements-billing-state/spec.md`
- `Customer-Facing Localization Adoption v1` -> anchored by `specs/252-platform-localization-v1/spec.md`, `specs/258-customer-review-productization/spec.md`, and `specs/260-governance-service-packaging/spec.md`

8
docs/product/roadmap.md
View File

@ -4,7 +4,7 @@ # Product Roadmap
> **Last reviewed:** 2026-05-12
> **Use for:** Current product roadmap, release themes, and prioritization context
> **Do not use for:** Implementation truth, spec completion status, or delivery guarantees without repo verification
> **Scoped maintenance:** 2026-05-12 roadmap alignment after the admin workspace navigation and tenant-owned surface repair candidate intake from the repo-verified navigation/panel audit; 2026-05-06 roadmap cleanup after ledger conflict resolution and cross-domain progress / indicator semantics candidate intake; 2026-05-02 repo-based roadmap drift correction, manual-promotion backlog alignment, and enterprise-SaaS deep-research calibration against current specs, standards, and product-truth docs.
> **Scoped maintenance:** 2026-05-15 Decision Register reconciliation update after Spec 306; 2026-05-12 roadmap alignment after the admin workspace navigation and tenant-owned surface repair candidate intake from the repo-verified navigation/panel audit; 2026-05-06 roadmap cleanup after ledger conflict resolution and cross-domain progress / indicator semantics candidate intake; 2026-05-02 repo-based roadmap drift correction, manual-promotion backlog alignment, and enterprise-SaaS deep-research calibration against current specs, standards, and product-truth docs.
>
> Strategic thematic blocks and release trajectory.
> This is the "big picture" — not individual specs.
@ -29,7 +29,7 @@ ## Current Productization & Moat Priorities
| Order | Theme | Alignment status | Repo truth | Why now | Queue posture |
|---|---|---|---|---|---|
| 1 | Customer Review Workspace Productization v1 | repo-verified, productization gap | Customer-safe review consumption is repo-real through Specs 249, 258, 259, 260, and 263, but the calm sellable surface still needs final productization discipline | clearest sellability lever for Governance-of-Record without creating a parallel customer portal | spec-backed follow-through |
| 2 | Decision-Based Governance Inbox + Decision Register v1 | repo-verified, productization gap, roadmap recommendation | Governance inbox, findings queues, alerts, review follow-up, and Specs 250/257 already anchor the decision surface; a bounded decision-register and approval follow-through is still open | biggest remaining operator workflow gap and the cleanest defense against admin-tool sprawl | manual promotion only for the decision-register follow-through |
| 2 | Decision-Based Governance Inbox + Decision Register follow-up | repo-verified, productization gap, roadmap recommendation | Governance inbox, findings queues, alerts, review follow-up, Specs 250/257, and the Spec 265 operator Decision Register are repo-verified; only narrow proof-link and customer-safe follow-through remain open | biggest remaining operator workflow gap and the cleanest defense against admin-tool sprawl | no Greenfield v1; manual promotion only for the narrow follow-up |
| 3 | Governance Artifact Lifecycle & Retention v1 | foundation-only, roadmap recommendation, spec candidate | Spec 262 and the lifecycle-governance standard provide taxonomy-first guardrails, but governance-artifact runtime semantics are not yet productized | new trust, auditability, export, and retention lever for evidence snapshots, stored reports, review packs, and decision records | manual promotion only |
| 4 | Commercial Entitlements & Billing-State Lifecycle v1 | repo-verified, foundation-only, productization gap | Specs 247 and 251 already resolve plan and lifecycle posture, but broader commercial-state-to-artifact-access rules and later billing truth remain open | SaaS trust and lifecycle maturity matter before broader packaging, scale, or AI work | spec-backed follow-through plus narrower billing follow-through |
| 5 | External Support Desk / PSA Handoff v1 | repo-verified, productization gap | Spec 256 and the current bounded handoff service already exist, but the portfolio-safe handoff story is still not fully productized | MSP integration should compress follow-through work without turning TenantPilot into a helpdesk | spec-backed follow-through |
@ -445,7 +445,7 @@ ## Infrastructure & Platform Debt
| Auditor-ready executive export is not yet productized | Review truth still stops short of calm auditor-/executive-ready delivery even though the spec package now exists | Covered by `specs/263-auditor-pack-executive-export/spec.md` |
| Cross-tenant promotion execution is missing | Compare preview and preflight stop short of the actual portfolio action even though the execution spec package now exists on this branch | Covered by `specs/264-cross-tenant-promotion-execution/spec.md` |
| Admin workspace navigation contract drift remains open | Inventory and adjacent tenant-owned admin surfaces can still conflict between workspace-home clean-sidebar rules and valid environment-bound admin routing, which risks product breaks and stale hide-first test assumptions | Covered by the Admin Workspace Navigation & Tenant-owned Surface Repair candidate group in `docs/product/spec-candidates.md` |
| Governance decision register and approval workflow is missing | Decision-based operating still lacks a bounded approval-ready closure and decision-record package with explicit audit trail | Covered by the manual-promotion backlog in `docs/product/spec-candidates.md` |
| Decision Register proof-link productization is still pending | The Spec 265 operator register exists; direct evidence/report, `OperationRun`, and review-pack proof links are not fully productized on the register path | Covered by the narrow manual-promotion follow-up in `docs/product/spec-candidates.md` |
| Customer-facing localization adoption is incomplete | Repo-real locale groundwork is not yet fully productized across customer-safe governance surfaces | Covered by the manual-promotion backlog in `docs/product/spec-candidates.md` |
| Billing and subscription truth is missing | Commercial readiness still stops short of a durable billing/subscription truth layer | Covered by the manual-promotion backlog in `docs/product/spec-candidates.md` |
| Stored reports still lack a clear product surface | Retained evidence and review artifacts remain harder to consume than they should be | Covered by the manual-promotion backlog in `docs/product/spec-candidates.md` |
@ -471,7 +471,7 @@ ## Priority Ranking (Current Manual Promotion Order)
Parallel immediate repair lane: the Admin Workspace Navigation & Tenant-owned Surface Repair candidate group in `docs/product/spec-candidates.md` should be promoted when Inventory or adjacent tenant-owned admin surfaces drift behind stale hide-first navigation contracts. `admin-inventory-navigation-cutover` is the immediate repair slice; the repo-wide route audit, groups cutover, navigation-contract split, and tenant-panel dead-code retirement stay sequenced manual follow-through outside the main sellability ordering.
1. Decision Register & Approval Workflow v1
1. Decision Register evidence / OperationRun link polish
2. Governance Artifact Lifecycle & Retention v1
3. Billing & Subscription Truth Layer v1
4. Customer-Facing Localization Adoption v1

24
docs/product/spec-candidates.md
View File

@ -4,7 +4,7 @@ # Spec Candidates
> **Last reviewed:** 2026-05-12
> **Use for:** The active repo-based queue of spec candidates that may still need new or refreshed specs
> **Do not use for:** Proof that a candidate is already specced, implemented, or prioritized above the roadmap without repo verification
> **Scoped maintenance:** 2026-05-15 Spec 304 Tenant Panel dead-code retirement guardrail update; 2026-05-12 admin workspace navigation and tenant-owned surface repair candidate intake after the repo-verified navigation/panel audit; 2026-05-06 cross-domain progress and indicator semantics candidate intake; 2026-05-04 OperationRun progress maturity plus Tenant Dashboard active-operations summary candidate intake; 2026-05-03 OperationRun activity feedback candidate intake plus the 2026-05-02 repo-based queue re-audit and enterprise-SaaS deep-research alignment against current `specs/` truth, including Specs 263 and current-branch 264.
> **Scoped maintenance:** 2026-05-15 Spec 306 Decision Register reconciliation update; 2026-05-15 Spec 304 Tenant Panel dead-code retirement guardrail update; 2026-05-12 admin workspace navigation and tenant-owned surface repair candidate intake after the repo-verified navigation/panel audit; 2026-05-06 cross-domain progress and indicator semantics candidate intake; 2026-05-04 OperationRun progress maturity plus Tenant Dashboard active-operations summary candidate intake; 2026-05-03 OperationRun activity feedback candidate intake plus the 2026-05-02 repo-based queue re-audit and enterprise-SaaS deep-research alignment against current `specs/` truth, including Specs 263 and current-branch 264.
>
> Repo-based next-spec queue for TenantPilot.
> This file is not a wishlist. It tracks only open gaps that are still worth turning into new or refreshed specs.
@ -46,14 +46,14 @@ ### Customer Review Workspace v1
- **Deep-Research-derived sharpening**: Keep the lane focused on one customer-safe read-only review surface, findings summary, accepted-risk visibility, evidence viewer, review-pack download, management summary, RBAC/capability enforcement, and audit trail.
- **Non-goals**: no generic customer portal, no helpdesk surface, no raw diagnostics by default, no admin mirror.
### Decision-Based Governance Inbox + Decision Register v1
### Decision-Based Governance Inbox + Decision Register Follow-up
- **Status markers**: repo-verified, productization gap, roadmap recommendation
- **Roadmap lane**: Now
- **Current repo truth**: governance inbox, findings queues, operations attention, review follow-up, and Specs 250 and 257 already anchor the decision surface, but there is still no bounded decision-register follow-through.
- **Problem**: Findings, alerts, runs, and reviews still need one calmer decision layer with ownership, due state, reason, impact, next action, linked evidence, linked `OperationRun`, accepted-risk path, closure reason, and escalation hooks.
- **Deep-Research-derived sharpening**: treat the missing slice as decision-register and approval/closure follow-through over current inbox foundations, not as another queue page.
- **Non-goals**: no generic Kanban board, no PSA clone, no XDR incident console.
- **Current repo truth**: governance inbox, findings queues, operations attention, review follow-up, and Specs 250/257 already anchor the decision surface. Spec 265 plus current runtime/tests now also prove the bounded operator Decision Register is not Greenfield.
- **Problem**: The remaining gap is narrower than the former v1 candidate: direct evidence/report and `OperationRun` proof-link polish, plus later customer-safe or review-pack inclusion if productized.
- **Deep-Research-derived sharpening**: treat the next slice as a follow-up over Spec 265, not a new Decision Register or approval-engine rebuild.
- **Non-goals**: no generic Kanban board, no PSA clone, no XDR incident console, no new decision table, no duplicate approval engine.
### Governance Artifact Lifecycle & Retention v1
@ -980,13 +980,16 @@ #### `tenant-panel-dead-code-retirement`
- docs and tests clearly separate historical references from live runtime contracts
- guardrails fail if `/admin/t` or retired tenant-panel runtime logic returns
### Decision Register & Approval Workflow v1
### Decision Register Evidence / OperationRun Link Polish
- **Priority**: 1
- **Repo truth**: governance inbox and convergence are spec-backed and partly repo-real, but the bounded decision-register and approval workflow is still a distinct follow-up gap.
- **Why promotable now**: it is the highest-value unspecced operator follow-through once inbox and review consumption are already grounded.
- **Why manual promotion only**: this must stay a deliberate product choice because v1 should remain narrow: owner, due date, status, reason, impact, next action, linked evidence, linked `OperationRun`, accepted-risk path, closure reason, escalation hook, and optional approval or closure semantics without autonomous remediation.
- **Status**: reconciled with Spec 265; narrow productization follow-up pending; moved out of Greenfield scope.
- **Repo truth**: Spec 265, `DecisionRegister`, `GovernanceDecisionRegisterBuilder`, FindingException detail handoff, and focused tests are repo-verified. The broad Decision Register & Approval Workflow v1 candidate is no longer an open Greenfield candidate.
- **Why promotable now**: Spec 306 classifies the current register as partial productization and identifies the narrowest next step as proof-link polish, not a rebuild.
- **Why manual promotion only**: this must stay a deliberate product choice because the follow-up should only expose existing evidence/report and `OperationRun` truth where it already exists, preserve existing approval/closure ownership, and avoid a new workflow engine.
- **Anchors**:
- `specs/265-decision-register-approval/spec.md`
- `specs/306-decision-register-reconciliation/decision-register-reconciliation.md`
- `specs/250-decision-governance-inbox/spec.md`
- `specs/257-governance-decision-convergence/spec.md`
- `docs/product/roadmap.md`
@ -1156,6 +1159,7 @@ ## Promoted to Spec
- Workspace, Tenant & Managed Object Lifecycle Governance v1 -> Spec 262 (`lifecycle-governance-taxonomy`)
- Auditor Pack Delivery & Executive Export v1 -> Spec 263 (`auditor-pack-executive-export`)
- Cross-Tenant Promotion Execution v1 -> Spec 264 (`cross-tenant-promotion-execution`)
- Decision Register & Approval Workflow v1 -> Spec 265 (`decision-register-approval`), reconciled by Spec 306; broad Greenfield scope closed, narrow proof-link follow-up remains manual
- Queued Execution Reauthorization and Scope Continuity -> Spec 149 (`queued-execution-reauthorization`)
- Livewire Context Locking and Trusted-State Reduction -> Spec 152 (`livewire-context-locking`)
- Evidence Domain Foundation -> Spec 153 (`evidence-domain-foundation`)

53
specs/306-decision-register-reconciliation/checklists/requirements.md Normal file
View File

@ -0,0 +1,53 @@
# Requirements Checklist: Decision Register Reconciliation & Productization Follow-up
**Purpose**: Validate that Spec 306 is ready for a docs-only reconciliation implementation and does not duplicate Spec 265.
**Created**: 2026-05-15
**Feature**: `specs/306-decision-register-reconciliation/spec.md`
## Preparation Quality
- [x] The selected candidate was directly provided by the user.
- [x] The spec is docs-first and reconciliation-only.
- [x] Spec 265 is treated as existing repo truth context, not rewritten.
- [x] Spec 305's no-Greenfield Decision Register condition is carried forward.
- [x] No application runtime implementation is planned in 306.
- [x] No tests are planned to be created or edited.
- [x] Product-doc edits are conditional, minimal, and limited to proven Decision Register drift.
## Required Artifact
- [x] The spec requires `specs/306-decision-register-reconciliation/decision-register-reconciliation.md`.
- [x] The required artifact structure is listed in `spec.md`.
- [x] The artifact must include Spec 265 summary, runtime evidence, test evidence, product-doc drift, capability matrix, sellability classification, gaps, recommendation, validation evidence, and close-out notes.
- [x] Required status vocabulary is explicit.
- [x] Unsupported implementation claims are forbidden.
## Scope Safety
- [x] No migrations, models, services, Filament pages/resources, tests, routes, providers, UI assets, policies, jobs, queues, notifications, or runtime behavior are in scope.
- [x] No broad roadmap rewrite is in scope.
- [x] No Greenfield Decision Register v1 rebuild is in scope.
- [x] Any required runtime work must become a future follow-up spec rather than hidden 306 scope.
## Evidence Requirements
- [x] Spec 265 evaluation is required.
- [x] Runtime inventory is required.
- [x] Focused test inspection and execution are required where paths exist.
- [x] Product docs drift assessment is required.
- [x] Missing test paths must be recorded as `not applicable`.
- [x] Validation outcomes must be copied into the reconciliation artifact.
## Next-Step Decision
- [x] Sellability classification must be exactly one of `foundation-only`, `partial productization`, `near sellable`, `sellable`, or `not implemented`.
- [x] Recommended next action must be exactly one of the allowed categories.
- [x] Any 307 Decision Register follow-up must be narrow and must not duplicate Spec 265.
- [x] If Decision Register is done enough, the artifact must allow 307 to become a different productization feature.
## Validation Requirements
- [x] `git diff --check` is required.
- [x] `git status --short --branch` scope check is required.
- [x] Final close-out must state runtime files changed: none.

284
specs/306-decision-register-reconciliation/decision-register-reconciliation.md Normal file
View File

@ -0,0 +1,284 @@
# Decision Register Reconciliation
## Executive Conclusion
Decision Register is repo-verified and implemented as the bounded Spec 265 operator register over existing `FindingException` and append-only `FindingExceptionDecision` truth.
A broad new `Decision Register v1` or `Decision Register & Approval Workflow v1` spec should not be created. Spec 265 runtime is usable: the `/admin/governance/decisions` page exists, is registered in the admin panel, is backed by `GovernanceDecisionRegisterBuilder`, links into the existing FindingException detail surface, and focused tests pass.
Sellability classification: `partial productization`.
Reason: the operator-facing register, source linkage, workspace/environment isolation, detail handoff, and existing approval/closure audit semantics are implemented. The remaining gap is not a rebuild; it is a narrow productization gap around direct evidence/report/OperationRun/review-pack link polish and customer-safe decision consumption readiness.
Recommended next action: `narrow follow-up spec required`.
Primary follow-up candidate: `decision-register-evidence-operationrun-link-polish`.
## Scope Boundary
- `repo-verified`: this reconciliation inspected specs, runtime, tests, product docs, and validation output.
- `not applicable`: no runtime implementation was performed for Spec 306.
- `not applicable`: no migrations, models, services, Filament pages/resources, routes, providers, jobs, policies, UI assets, or tests were changed.
- `follow-up required`: product docs needed minimal sync because they still framed Decision Register as missing or future-only.
## Inputs Reviewed
Specs and audits:
- `specs/265-decision-register-approval/spec.md`
- `specs/265-decision-register-approval/plan.md`
- `specs/265-decision-register-approval/tasks.md`
- `specs/265-decision-register-approval/checklists/requirements.md`
- `specs/305-feature-readiness-gate-audit/feature-readiness-audit.md`
- `specs/306-decision-register-reconciliation/spec.md`
- `specs/306-decision-register-reconciliation/plan.md`
- `specs/306-decision-register-reconciliation/tasks.md`
Runtime evidence:
- `apps/platform/app/Filament/Pages/Governance/DecisionRegister.php`
- `apps/platform/resources/views/filament/pages/governance/decision-register.blade.php`
- `apps/platform/app/Support/GovernanceDecisions/GovernanceDecisionRegisterBuilder.php`
- `apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php`
- `apps/platform/app/Support/GovernanceInbox/GovernanceInboxSectionBuilder.php`
- `apps/platform/app/Filament/Resources/FindingExceptionResource.php`
- `apps/platform/app/Filament/Resources/FindingExceptionResource/Pages/ViewFindingException.php`
- `apps/platform/app/Services/Findings/FindingExceptionService.php`
- `apps/platform/app/Models/FindingException.php`
- `apps/platform/app/Models/FindingExceptionDecision.php`
- `apps/platform/app/Models/FindingExceptionEvidenceReference.php`
- `apps/platform/app/Providers/Filament/AdminPanelProvider.php`
- `apps/platform/bootstrap/providers.php`
- `apps/platform/database/migrations/2026_03_19_000001_create_finding_exceptions_table.php`
- `apps/platform/database/migrations/2026_03_19_000002_create_finding_exception_decisions_table.php`
- `apps/platform/database/migrations/2026_03_19_000003_create_finding_exception_evidence_references_table.php`
Product docs:
- `docs/product/spec-candidates.md`
- `docs/product/implementation-ledger.md`
- `docs/product/roadmap.md`
Routes:
- Laravel route inspection returned `GET|HEAD admin/governance/decisions` and `GET|HEAD admin/governance/inbox`.
## Spec 265 Summary
Spec 265 promised a bounded Decision Register, not a new workflow platform.
Scope classification:
| Area | Spec 265 promise | Current classification |
|---|---|---|
| Data model | Reuse `FindingException`, `FindingExceptionDecision`, `FindingExceptionEvidenceReference`; no new `GovernanceDecision` table. | `implemented` |
| UI surface | Add one workspace-level `/admin/governance/decisions` Filament page. | `implemented` |
| Governance Inbox integration | Keep Governance Inbox as an adjacent decision-entry surface and avoid a second decision truth. | `partial productization` |
| Finding integration | Register rows derive from FindingException truth and open the existing detail page. | `implemented` |
| Approval semantics | Existing approve/reject actions stay on queue/detail surfaces; no inline register approval. | `implemented` |
| Closure semantics | Existing renewal/revocation/rejection state and recently closed register view show closure reason. | `implemented` |
| Evidence links | Use existing proof only; missing proof must stay truthful. | `partial productization` |
| OperationRun links | Optional deep-link only when current proof already exposes it; no run start path. | `foundation-only` |
| RBAC/capabilities | Workspace membership first; view via `FINDING_EXCEPTION_VIEW`; mutations keep existing manage/approve gates. | `implemented` |
| Audit/event semantics | Existing FindingExceptionService audit entries stay authoritative. | `implemented` |
| Tests | Focused Unit and Feature coverage plus browser smoke allowance. | `implemented` |
| Docs | Product docs should stop treating Decision Register as Greenfield. | `stale docs` |
Spec 265 tasks are marked complete in `specs/265-decision-register-approval/tasks.md`. Its explicit non-goals were no new decision table, no generic task engine, no customer-facing decision portal, no inline register mutations, no autonomous escalation, no new review-pack workflow, and no new OperationRun start path.
## Runtime Evidence Matrix
| Runtime area | Status | Repo evidence | Caveat |
|---|---|---|---|
| Admin page route | `implemented` | `DecisionRegister` slug is `governance/decisions`; route inspection shows `admin/governance/decisions`. | Route is operator/admin only. |
| Panel registration | `implemented` | `AdminPanelProvider` lists `DecisionRegister::class` in `->pages([...])`; `bootstrap/providers.php` registers `AdminPanelProvider`. | No provider change needed. |
| Register builder | `implemented` | `GovernanceDecisionRegisterBuilder::build()` derives open and recently closed rows from `FindingException` and `FindingExceptionDecision`. | Builder does not create a persisted decision projection. |
| Register UI | `implemented` | `DecisionRegister.php` defines Filament table columns for environment, status, impact, owner, review due, proof, next action, closure reason; Blade view hosts the table and state toggles. | No inline mutation actions. |
| Decision detail handoff | `implemented` | `DecisionRegister::decisionUrl()` opens `FindingExceptionResource` view with `CanonicalNavigationContext::forDecisionRegister()`. | Detail page owns lifecycle actions. |
| Detail summary/back action | `implemented` | `ViewFindingException` adds `return_to_decision_register` and register-aware subheading when navigation context source is `governance.decision_register`. | Summary is context only, not a separate workflow. |
| Decision persistence | `implemented` | `finding_exceptions` has current status, validity, owner, due/review and closure fields; `finding_exception_decisions` stores append-only decision history. | No generic decision table. |
| Evidence references | `implemented` | `finding_exception_evidence_references` model and migration exist; detail infolist renders evidence references; register shows proof count from `evidence_summary`. | Direct artifact URLs from register are not fully productized. |
| Approval lifecycle | `implemented` | `FindingExceptionService::approve()` and `reject()` write decision rows, state fields, and audit entries. | Actions are outside the register page by design. |
| Renewal/revocation lifecycle | `implemented` | `FindingExceptionService::renew()` and `revoke()` write decision rows, state fields, evidence references, and audit entries. | Actions are outside the register page by design. |
| Governance Inbox relationship | `partial productization` | `GovernanceInboxSectionBuilder` contains a `finding_exceptions` family and routes to `FindingExceptionsQueue`. | It does not directly route to Decision Register. |
| Review/customer workspace relationship | `foundation-only` | `EnvironmentReviewComposer` packages `governance_decisions`; `CustomerReviewWorkspace` summarizes accepted-risk accountability. | Not the same as a customer-safe Decision Register. |
| OperationRun relationship | `foundation-only` | Finding and review/report layers carry OperationRun links elsewhere; Spec 265 allowed optional proof links only. | Decision Register itself does not expose direct OperationRun links. |
| Audit trail | `implemented` | `FindingExceptionService` logs `FindingExceptionRequested`, `Approved`, `Rejected`, `RenewalRequested`, `Renewed`, and `Revoked` actions. | Register page views are not a new audit stream. |
## Test Evidence Matrix
| Test file | What it proves | Validation result | Caveat |
|---|---|---|---|
| `tests/Unit/Support/GovernanceDecisions/GovernanceDecisionRegisterBuilderTest.php` | Open/recently closed derivation, visible tenant filtering, owner handling, closure reason, next-action labels. | Included in 27 passed / 137 assertions. | Does not prove UI rendering. |
| `tests/Feature/Governance/DecisionRegisterPageTest.php` | Page renders open and recently closed rows, hides hidden tenants, shows truthful filtered empty states. | Included in 27 passed / 137 assertions. | Does not prove browser interaction. |
| `tests/Feature/Governance/DecisionRegisterAuthorizationTest.php` | Workspace chooser redirect, non-member 404, no-visible-decisions 403, hidden navigation, explicit tenant 404, recently closed redirect. | Included in 27 passed / 137 assertions. | No mutation actions expected. |
| `tests/Feature/Findings/FindingExceptionDecisionRegisterNavigationTest.php` | Register row URL preserves navigation context and back link. | Included in 27 passed / 137 assertions. | Link goes to FindingException detail, not a register detail page. |
| `tests/Feature/Findings/FindingExceptionDetailDecisionSummaryTest.php` | Detail page keeps existing renew/revoke actions and adds register return action/subheading. | Included in 27 passed / 137 assertions. | Approve/reject are queue-owned in existing flow. |
| `tests/Feature/Findings/FindingExceptionDecisionRegisterBoundariesTest.php` | Register remains read-only and excludes terminal rows outside 30-day window. | Included in 27 passed / 137 assertions. | Evidence/OperationRun direct links are not proven here. |
| `tests/Unit/Support/GovernanceInbox/GovernanceInboxSectionBuilderTest.php` | Governance Inbox includes finding exception family, source links, canonical order, hidden family behavior. | Included in 27 passed / 137 assertions. | It routes to FindingExceptionsQueue, not Decision Register. |
| `tests/Feature/Governance/GovernanceInboxPageTest.php` | Governance Inbox renders attention sections and capability-hidden finding exceptions lane. | Included in 27 passed / 137 assertions. | Not a Decision Register page test. |
| `tests/Feature/Governance/GovernanceInboxAuthorizationTest.php` | Governance Inbox workspace redirects, non-member 404, no family 403, tenant-scope 404. | Included in 27 passed / 137 assertions. | Not specific to Decision Register. |
| `tests/Unit/Findings/FindingExceptionDecisionTest.php` | Decision rows are append-only: update/delete throw `LogicException`. | 7 passed / 91 assertions with workflow lane. | Unit-only persistence guard. |
| `tests/Feature/Findings/FindingExceptionWorkflowTest.php` | Request/approve/reject writes state and audit entries. | 7 passed / 91 assertions with workflow lane. | Uses existing queue/detail flow. |
| `tests/Feature/Findings/FindingExceptionRenewalTest.php` | Renewal preserves history, evidence references, approval/rejection semantics, audit entries. | 7 passed / 91 assertions with workflow lane. | Not initiated from register. |
| `tests/Feature/Findings/FindingExceptionRevocationTest.php` | Revoke writes terminal state, reason, timestamp, decision history, audit entry. | 7 passed / 91 assertions with workflow lane. | Not initiated from register. |
| Evidence/review/customer workspace tests | EvidenceSnapshot, EnvironmentReview, CustomerReviewWorkspace, pack access, launch links, artifact deep links. | 51 passed / 362 assertions. | Supporting evidence only, not direct register productization. |
| OperationRun/link guard tests | Operation dashboard drill-through, legacy run route guards, provider redirects, canonical environment route, policy-version links. | 15 passed / 98 assertions. | Supporting link/route evidence only. |
## Product Docs Drift
| Product doc | Drift classification | Repo evidence | Minimal sync performed |
|---|---|---|---|
| `docs/product/spec-candidates.md` | `stale docs`, understate repo truth, duplicate candidate risk | It listed broad Decision Register & Approval Workflow v1 as an open Priority 1 candidate even though Spec 265/runtime/tests exist. | Yes: broad Greenfield candidate moved to reconciled Spec 265 truth and narrowed follow-up. |
| `docs/product/implementation-ledger.md` | `stale docs`, understate repo truth | It listed Decision Register & Approval Workflow v1 under Not Implemented and as still missing. | Yes: added Decision Register operator surface truth and replaced broad missing gap with narrow productization gap. |
| `docs/product/roadmap.md` | `stale docs`, understate repo truth | It said bounded decision-register follow-through was still open and ranked broad Decision Register v1 first. | Yes: small notes now say Spec 265 register is repo-verified and only narrow follow-up remains. |
## Capability Matrix
| Capability | Status | Repo evidence | Test evidence | Caveat | Recommended action |
|---|---|---|---|---|---|
| Decision Register page | `implemented` | `DecisionRegister.php`, Blade host, admin route `admin/governance/decisions` | `DecisionRegisterPageTest`, `DecisionRegisterAuthorizationTest` | Operator/admin only. | Keep; do not rebuild. |
| Decision detail or summary surface | `implemented` | `ViewFindingException`, `FindingExceptionResource::infolist()` | `FindingExceptionDetailDecisionSummaryTest` | Detail is FindingException detail, not a separate decision detail. | Keep detail-owned lifecycle. |
| Decision source linkage | `implemented` | `decisionUrl()` uses `FindingExceptionResource::getUrl()` and `CanonicalNavigationContext` | `FindingExceptionDecisionRegisterNavigationTest` | Link source is accepted-risk exception truth. | Keep. |
| FindingException integration | `implemented` | `FindingException`, `FindingExceptionDecision`, service and resource | Decision Register and FindingException workflow tests | Register covers this decision family only. | Keep as bounded v1 truth. |
| Governance Inbox integration | `partial productization` | `GovernanceInboxSectionBuilder` finding exception family routes to queue | GovernanceInbox tests | No direct Decision Register CTA. | Consider separate IA polish only if needed. |
| Owner/assignment semantics | `implemented` | `owner_user_id`, owner relationship, register owner column, builder owner_name | Builder and page tests | Missing owner remains visible. | Keep. |
| Due state semantics | `implemented` | `review_due_at`, `expires_at`, register review due column, next action labels | Builder/page tests | No shared due-state taxonomy beyond current exception logic. | Keep for v1; avoid widening. |
| Approval semantics | `implemented` | `FindingExceptionService::approve()` / `reject()`, queue/detail actions | Workflow tests | Not inline on register by design. | Keep existing owner surface. |
| Closure semantics | `implemented` | rejected/revoked/superseded terminal state, reasons, timestamps, recently closed window | Boundary/workflow/revocation tests | Closed window is 30 days. | Keep. |
| Audit/event semantics | `implemented` | `AuditActionId` and `FindingExceptionService` AuditLogger calls | Workflow/renewal/revocation tests | No register page-view audit. | Keep existing mutation audit trail. |
| RBAC/capability enforcement | `implemented` | `DecisionRegister::canAccess()`, `FINDING_EXCEPTION_VIEW`, detail manage/approve gates | Authorization and workflow tests | Register uses view capability; mutations use existing manage/approve gates. | Keep. |
| Workspace isolation | `implemented` | Workspace context checks and workspace-scoped queries | Authorization tests | No visible rows returns 403 for default unfiltered register. | Keep. |
| Environment isolation | `implemented` | Tenant filters validated against visible decision tenants; out-of-scope tenant 404 | Page/authorization tests | Filtered empty state differs from out-of-scope 404. | Keep. |
| Evidence/report linkage | `partial productization` | `evidence_summary` count on register; `evidenceReferences` detail section | Renewal test; EvidenceSnapshot tests support artifact truth | Direct evidence/report links from register are not fully productized. | `follow-up required`: link polish. |
| OperationRun linkage | `foundation-only` | `OperationRunLinks` exists elsewhere; reviews/findings can carry run references | OperationRun/link guard tests | Decision Register does not expose direct run links. | Include in narrow link-polish follow-up. |
| Review/review-pack linkage | `foundation-only` | `EnvironmentReviewComposer` packages governance decisions; review packs have operation/evidence links | Evidence/review/customer workspace tests | Not a direct Decision Register review-pack inclusion. | Adjacent follow-up candidate only. |
| Customer-safe consumption readiness | `productization gap` | CustomerReviewWorkspace summarizes accepted-risk accountability; Decision Register remains admin/operator | CustomerReviewWorkspace tests | Customer-safe Decision Register output is not implemented. | Adjacent follow-up after link polish. |
| Product docs alignment | `stale docs` | Product docs listed broad v1 as missing/future | This artifact and docs diff | Product docs were corrected minimally. | Keep docs synchronized after 307. |
## Sellability Classification
Classification: `partial productization`.
Short reason: Decision Register is implemented and test-proven for operator use, but not yet `near sellable` or `sellable` as a decision product layer because direct proof links, OperationRun/review-pack linkage, and customer-safe consumption remain productization gaps.
It is not `foundation-only` because the operator-facing page, row model, navigation, authorization, and detail handoff are implemented.
It is not `not implemented` because Spec 265 runtime and tests are repo-verified.
## Open Gaps
| Gap | Status | Evidence | Recommended action |
|---|---|---|---|
| Broad product docs still treated Decision Register as future-only before this spec. | `stale docs` | Product-doc references in spec-candidates, ledger, roadmap. | Minimal docs sync completed under Spec 306. |
| Register shows proof count but not direct evidence/report artifact links. | `productization gap` | `DecisionRegister.php` reads `evidence_summary.reference_count`; detail renders evidence references. | Primary 307 follow-up. |
| Decision Register does not expose direct OperationRun links. | `productization gap` | OperationRun link helpers exist elsewhere, but no direct register/run link in `DecisionRegister.php` or builder. | Primary 307 follow-up. |
| Decision Register is not included as a customer-safe review-pack/register surface. | `productization gap` | CustomerReviewWorkspace and EnvironmentReviewComposer handle accepted-risk/governance-decision summaries, not a customer-safe register. | Adjacent follow-up, not bundled unless 307 remains narrow. |
| Governance Inbox does not directly route to Decision Register. | `partial productization` | Governance Inbox finding-exception family routes to FindingExceptionsQueue. | Optional IA polish only if product need is proven. |
## Recommended Next Action
Recommended next action category: `narrow follow-up spec required`.
307 should be a small Decision Register follow-up, not a broad feature restart.
Recommended 307 name:
```text
307-decision-register-evidence-operationrun-link-polish
```
Recommended 307 scope:
- expose direct evidence/report proof links where existing `FindingExceptionEvidenceReference`, `EvidenceSnapshot`, `StoredReport`, or review-pack truth already exists
- expose direct OperationRun links only through existing helpers and only when current truth already has a run reference
- preserve FindingException as decision truth
- preserve existing approval/closure actions on queue/detail surfaces
- preserve workspace/environment isolation and non-member/out-of-scope denial semantics
- add no new decision table, no workflow engine, no review-pack redesign, no customer portal
## Candidate Follow-ups
Primary:
- `decision-register-evidence-operationrun-link-polish` - `follow-up required`
Adjacent candidates, not part of the primary 307 unless explicitly split:
- `decision-register-review-pack-inclusion` - `productization gap`
- `decision-register-customer-safe-summary` - `productization gap`
- `decision-register-governance-inbox-cta-polish` - `partial productization`
Do not name the follow-up:
- `Decision Register v1`
- `Decision-Based Governance Inbox v1`
- `Governance Workflow Platform`
- `Approval Engine`
## Validation Evidence
Focused Decision Register / Governance / FindingException lane:
```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/GovernanceDecisions/GovernanceDecisionRegisterBuilderTest.php tests/Unit/Support/GovernanceInbox/GovernanceInboxSectionBuilderTest.php tests/Feature/Governance/DecisionRegisterPageTest.php tests/Feature/Governance/DecisionRegisterAuthorizationTest.php tests/Feature/Governance/GovernanceInboxPageTest.php tests/Feature/Governance/GovernanceInboxAuthorizationTest.php tests/Feature/Findings/FindingExceptionDecisionRegisterNavigationTest.php tests/Feature/Findings/FindingExceptionDetailDecisionSummaryTest.php tests/Feature/Findings/FindingExceptionDecisionRegisterBoundariesTest.php
```
Result: passed, 27 tests, 137 assertions.
Supporting Evidence / Review / Customer Review / artifact link lane:
```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Evidence/EvidenceSnapshotResourceTest.php tests/Feature/Evidence/EvidenceSnapshotAuditLogTest.php tests/Feature/EnvironmentReview/EnvironmentReviewAuditLogTest.php tests/Feature/EnvironmentReview/EnvironmentReviewRegisterTest.php tests/Feature/EnvironmentReview/EnvironmentReviewRegisterRbacTest.php tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php tests/Feature/Reviews/CustomerReviewWorkspaceAuthorizationTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php tests/Feature/Filament/GovernanceArtifacts/GovernanceArtifactDeepLinkContractTest.php
```
Result: passed, 51 tests, 362 assertions.
Supporting OperationRun / link guard lane:
```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php tests/Feature/Operations/LegacyRunRoutesNotFoundTest.php tests/Feature/ProviderConnections/LegacyRedirectTest.php tests/Feature/RequiredPermissions/RequiredPermissionsLegacyRouteTest.php tests/Feature/Guards/ManagedEnvironmentCanonicalRouteContractTest.php tests/Feature/Filament/PolicyVersionResolvedReferenceLinksTest.php
```
Result: passed, 15 tests, 98 assertions.
FindingException lifecycle / audit lane:
```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Findings/FindingExceptionDecisionTest.php tests/Feature/Findings/FindingExceptionWorkflowTest.php tests/Feature/Findings/FindingExceptionRenewalTest.php tests/Feature/Findings/FindingExceptionRevocationTest.php
```
Result: passed, 7 tests, 91 assertions.
Browser smoke: `not applicable` for Spec 306 because no runtime UI, route, asset, or frontend behavior changed. Existing Spec 265 browser smoke remains repository evidence, but it was not rerun for this docs-only reconciliation.
Whitespace validation:
```bash
git diff --check
```
Result: passed, no whitespace errors.
Scope validation:
```bash
git status --short --branch
```
Result: passed. Changed files are limited to `docs/product/spec-candidates.md`, `docs/product/implementation-ledger.md`, `docs/product/roadmap.md`, and `specs/306-decision-register-reconciliation/`.
## Close-Out Notes
- Files created/updated under Spec 306: `spec.md`, `plan.md`, `tasks.md`, `checklists/requirements.md`, and `decision-register-reconciliation.md`.
- Product docs changed: `docs/product/spec-candidates.md`, `docs/product/implementation-ledger.md`, `docs/product/roadmap.md`.
- Runtime files changed: none.
- Spec 265 status summary: repo-verified bounded operator Decision Register implemented over existing FindingException decision truth.
- Runtime classification: `implemented` for operator register; `partial productization` overall due link/customer-safe gaps.
- Sellability classification: `partial productization`.
- Recommended next action: `narrow follow-up spec required`.
- 307 recommendation: Decision Register follow-up, specifically `decision-register-evidence-operationrun-link-polish`.
- Broad Greenfield Decision Register duplication: explicitly rejected.
- Focused test results: 27/137 Decision Register lane, 51/362 Evidence/Review lane, 15/98 OperationRun/link lane, 7/91 FindingException lifecycle lane, all passed.
- `git diff --check`: passed, no output.
- Scope check: passed; no `apps/platform/app`, `apps/platform/database`, `apps/platform/routes`, `apps/platform/resources`, `apps/platform/tests`, runtime config, providers, jobs, policies, services, UI assets, or migrations changed.

274
specs/306-decision-register-reconciliation/plan.md Normal file
View File

@ -0,0 +1,274 @@
# Implementation Plan: Decision Register Reconciliation & Productization Follow-up
**Branch**: `306-decision-register-reconciliation` | **Date**: 2026-05-15 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/306-decision-register-reconciliation/spec.md`
## Summary
Create a docs-only, repo-based reconciliation of Decision Register work after Spec 305. The implementation will inspect Spec 265, current runtime, focused tests, and product docs; produce `decision-register-reconciliation.md`; update product docs minimally if they are proven stale; run focused validation; and stop with a clear recommendation for whether 307 should be a narrow Decision Register follow-up or a different productization feature.
No application runtime, migrations, tests, routes, Filament resources/pages, policies, jobs, queues, providers, or UI assets will be changed.
## Technical Context
**Language/Version**: PHP 8.4.15, Laravel 12.52.0, Filament 5.2.1, Livewire 4.1.4
**Primary Dependencies**: Existing repository markdown, Spec Kit scripts/templates, Laravel/Filament runtime evidence, Pest v4 test suite evidence
**Storage**: N/A - no database changes; PostgreSQL runtime schema may be inspected as evidence only
**Testing**: Existing focused Pest tests only; no new or modified tests
**Validation Lanes**: confidence via focused existing tests, whitespace validation via `git diff --check`
**Target Platform**: Existing Laravel monolith in `apps/platform`, admin plane evidence only
**Project Type**: Web application repository, docs-only feature
**Performance Goals**: N/A - no runtime behavior changes
**Constraints**: No runtime scope creep, no broad Decision Register spec, no product-doc rewrite, no unsupported implementation claims
**Scale/Scope**: One reconciliation artifact plus optional minimal product-doc sync
## Inherited Baseline / Explicit Delta
### Inherited baseline
- Spec 265 defines `Decision Register & Approval Workflow v1`.
- Spec 265 task markers indicate implementation tasks are complete.
- Spec 305 records that Decision Register runtime pages, builders, navigation, and tests exist.
- Product docs still include Decision Register as a missing or future productization item in several locations.
### Explicit delta in this plan
- Add `decision-register-reconciliation.md`.
- Compare Spec 265 promises to current runtime/test truth.
- Classify current Decision Register sellability.
- Update product docs only if drift is proven and only in the smallest truthful way.
- Recommend exactly one next action category and, if needed, one narrow primary 307 follow-up.
## Likely Reviewed Repo Surfaces
### Spec and product docs
```text
specs/265-decision-register-approval/spec.md
specs/265-decision-register-approval/plan.md
specs/265-decision-register-approval/tasks.md
specs/265-decision-register-approval/checklists/requirements.md
specs/305-feature-readiness-gate-audit/spec.md
specs/305-feature-readiness-gate-audit/feature-readiness-audit.md
docs/product/spec-candidates.md
docs/product/implementation-ledger.md
docs/product/roadmap.md
```
### Runtime evidence targets
Exact paths must be repo-verified during implementation. Likely targets include:
```text
apps/platform/app/Filament/Pages/Governance/DecisionRegister.php
apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php
apps/platform/app/Support/GovernanceDecisions/GovernanceDecisionRegisterBuilder.php
apps/platform/app/Support/GovernanceInbox/GovernanceInboxSectionBuilder.php
apps/platform/app/Filament/Resources/FindingExceptionResource.php
apps/platform/app/Filament/Resources/FindingExceptionResource/Pages/ViewFindingException.php
apps/platform/app/Models/FindingException.php
apps/platform/app/Models/FindingExceptionDecision.php
apps/platform/app/Models/FindingExceptionEvidenceReference.php
apps/platform/app/Models/EvidenceSnapshot.php
apps/platform/app/Models/StoredReport.php
apps/platform/app/Models/EnvironmentReview.php
apps/platform/app/Models/ReviewPack.php
apps/platform/app/Models/OperationRun.php
apps/platform/app/Models/AuditLog.php
apps/platform/app/Providers/Filament/AdminPanelProvider.php
```
### Focused test evidence targets
```text
apps/platform/tests/Unit/Support/GovernanceDecisions/GovernanceDecisionRegisterBuilderTest.php
apps/platform/tests/Unit/Support/GovernanceInbox/GovernanceInboxSectionBuilderTest.php
apps/platform/tests/Feature/Governance/DecisionRegisterPageTest.php
apps/platform/tests/Feature/Governance/DecisionRegisterAuthorizationTest.php
apps/platform/tests/Feature/Governance/GovernanceInboxPageTest.php
apps/platform/tests/Feature/Governance/GovernanceInboxAuthorizationTest.php
apps/platform/tests/Feature/Findings/FindingExceptionDecisionRegisterNavigationTest.php
apps/platform/tests/Feature/Findings/FindingExceptionDetailDecisionSummaryTest.php
apps/platform/tests/Feature/Findings/FindingExceptionDecisionRegisterBoundariesTest.php
```
Supporting paths are inspected and run only if they exist.
## UI / Surface Guardrail Plan
- **Guardrail scope**: no operator-facing surface change.
- **Native vs custom classification summary**: N/A.
- **Shared-family relevance**: audit-only evidence for governance, findings, evidence/report viewers, reviews, OperationRun links, RBAC, and audit.
- **State layers in scope**: none.
- **Audience modes in scope**: N/A.
- **Decision/diagnostic/raw hierarchy plan**: N/A for new work; existing Decision Register/detail surfaces are inspected for customer-safe readiness.
- **Raw/support gating plan**: N/A for new work.
- **One-primary-action / duplicate-truth control**: The audit prevents duplicate feature truth by distinguishing Spec 265 runtime from any legitimate narrow follow-up.
- **Handling modes by drift class or surface**: review-mandatory for product-doc drift.
- **Repository-signal treatment**: repo evidence controls all claims.
- **Special surface test profiles**: existing tests only.
- **Required tests or manual smoke**: existing focused tests; no browser smoke unless runtime UI changes are unexpectedly discovered, which should not happen in this spec.
- **Exception path and spread control**: any need for runtime change is a stop condition or future spec, not in-scope 306 work.
- **Active feature PR close-out entry**: Guardrail.
## Shared Pattern & System Fit
- **Cross-cutting feature marker**: yes, audit-only.
- **Systems touched**: Spec Kit package and product truth docs if stale.
- **Shared abstractions reused**: no runtime abstractions changed.
- **New abstraction introduced? why?**: none.
- **Why the existing abstraction was sufficient or insufficient**: current runtime and tests are sufficient for evidence gathering; product docs may need correction.
- **Bounded deviation / spread control**: product-doc changes must be explicit, minimal, and Decision Register-only.
## OperationRun UX Impact
- **Touches OperationRun start/completion/link UX?**: no runtime change.
- **Central contract reused**: N/A.
- **Delegated UX behaviors**: N/A.
- **Surface-owned behavior kept local**: none.
- **Queued DB-notification policy**: N/A.
- **Terminal notification path**: N/A.
- **Exception path**: none.
## Provider Boundary & Portability Fit
- **Shared provider/platform boundary touched?**: no.
- **Provider-owned seams**: N/A.
- **Platform-core seams**: N/A.
- **Neutral platform terms / contracts preserved**: Decision Register, Governance Inbox, FindingException, Evidence/StoredReport, Review/ReviewPack, OperationRun, AuditLog.
- **Retained provider-specific semantics and why**: none new.
- **Bounded extraction or follow-up path**: N/A.
## Filament / Laravel Compliance Posture
- Filament v5 explicitly targets Livewire v4.0+; this repository reports Livewire 4.1.4.
- No panel provider is added or changed. Laravel 11+/12 provider registration remains in `apps/platform/bootstrap/providers.php`.
- No globally searchable resource is added or changed. Existing searchable resources, if cited, must be classified from repo evidence.
- No destructive action is added or changed. Existing destructive or lifecycle actions are inspected for confirmation and authorization evidence only.
- No asset strategy changes are planned. If the audit cites registered assets, deployment remains responsible for `cd apps/platform && php artisan filament:assets`; 306 itself adds no assets.
- Testing plan is focused existing Pest tests for pages/builders/actions; no Livewire or Filament tests are added.
## Constitution Check
*GATE: Must pass before implementation begins and again before close-out.*
- Inventory-first: PASS. The work only records existing truth.
- Read/write separation: PASS. No runtime writes or remote calls.
- Graph contract path: PASS. No Graph calls are introduced.
- Deterministic capabilities: PASS. Existing capability evidence is inspected only.
- Workspace and tenant/environment isolation: PASS. Existing checks and tests are inspected and classified.
- RBAC-UX: PASS. No authorization changes; existing 404/403 behavior is evidence.
- OperationRun / Ops-UX: PASS by non-use. Existing links are evidence only.
- Test governance: PASS. No tests are created; existing focused tests are run for evidence.
- Proportionality / no premature abstraction: PASS. One docs artifact is the narrowest planning correction.
- Persisted truth: PASS. No runtime persisted truth is added.
- Behavioral state: PASS. No runtime states are added.
- Shared pattern first: PASS. Product-doc synchronization uses existing docs and history.
- Filament-native UI: PASS by non-change.
- UI/UX surface taxonomy: PASS by non-change.
**Gate evaluation**: PASS for preparation.
## Test Governance Check
- **Test purpose / classification by changed surface**: N/A for changed surfaces; existing Unit and Feature tests are run as evidence.
- **Affected validation lanes**: confidence and docs whitespace.
- **Why this lane mix is the narrowest sufficient proof**: The only changed artifacts are docs; existing tests prove or caveat claims about current runtime.
- **Narrowest proving command(s)**:
- focused Decision Register / Governance / FindingException test lane
- focused Evidence / Review / GovernanceArtifact link lane if paths exist
- focused OperationRun / route/link guard lane if paths exist
- `git diff --check`
- `git status --short --branch`
- **Fixture / helper / factory / seed / context cost risks**: none.
- **Expensive defaults or shared helper growth introduced?**: no.
- **Heavy-family additions, promotions, or visibility changes**: none.
- **Surface-class relief / special coverage rule**: N/A.
- **Closing validation and reviewer handoff**: Review the reconciliation artifact, product-doc diff if any, validation results, and no-runtime-change status.
- **Budget / baseline / trend follow-up**: none.
- **Review-stop questions**: unsupported implementation claim, overbroad follow-up naming, product-doc rewrite, runtime file diff, unrecorded test failure.
- **Escalation path**: stop and split to a future spec if runtime change is needed.
- **Active feature PR close-out entry**: Guardrail.
- **Test-governance outcome**: keep.
## Project Structure
### Documentation (this feature)
```text
specs/306-decision-register-reconciliation/
├── spec.md
├── plan.md
├── tasks.md
├── decision-register-reconciliation.md
└── checklists/
└── requirements.md
```
### Product Docs (conditional)
```text
docs/product/spec-candidates.md
docs/product/implementation-ledger.md
docs/product/roadmap.md
```
Only Decision Register truth-sync edits are allowed, and only if stale docs are proven.
**Structure Decision**: keep all new audit output inside the 306 spec package. Product docs are edited only as sync targets, not as the primary artifact.
## Implementation Phases
### Phase 0 - Preparation Confirmation
- Confirm branch and status.
- Re-read Spec 265, Spec 305, product docs, and relevant runtime/test path lists.
### Phase 1 - Spec 265 and Runtime Inventory
- Summarize what Spec 265 promised and what its tasks/checklist show.
- Search runtime for Decision Register, Governance Inbox, FindingException decision, evidence, review, OperationRun, capability, and audit integration.
- Record repo evidence paths only.
### Phase 2 - Test Inventory and Focused Validation
- Inspect focused tests and summarize what assertions prove.
- Run focused test lanes where paths exist.
- Record exact command output summaries, skipped paths, failures, and residual risk.
### Phase 3 - Product Docs Drift Assessment
- Inspect `docs/product/spec-candidates.md`, `docs/product/implementation-ledger.md`, and `docs/product/roadmap.md`.
- Classify each as accurate, stale, understated, overstated, or duplicate candidate risk.
- Apply minimal docs sync only where needed.
### Phase 4 - Reconciliation Artifact
- Create `decision-register-reconciliation.md` with the required structure.
- Add runtime evidence matrix, test evidence matrix, product docs drift section, capability matrix, sellability classification, gap list, and one recommended next action.
### Phase 5 - Scope and Whitespace Validation
- Confirm only allowed files changed.
- Run `git diff --check`.
- Update close-out notes and task checkboxes as appropriate.
## Risk Controls
- Reject any runtime change during 306.
- Reject any product-doc edit that rewrites roadmap broadly.
- Reject any implementation claim without repo evidence.
- Reject broad follow-up names such as `Decision Register v1`, `Governance Workflow Platform`, or `Approval Engine`.
- Treat absent test paths as `not applicable` rather than inventing coverage.
- If focused validation fails, document the failure and residual risk; do not fix tests or runtime under 306.
## Rollout Considerations
- No deployment effect.
- No environment variables.
- No migrations.
- No queues or cron workers.
- No storage or volume changes.
- No asset build requirement added by this spec.
- Staging/production validation impact is N/A for runtime; docs can be reviewed in normal PR flow.

479
specs/306-decision-register-reconciliation/spec.md Normal file
View File

@ -0,0 +1,479 @@
# Feature Specification: Decision Register Reconciliation & Productization Follow-up
**Feature Branch**: `306-decision-register-reconciliation`
**Created**: 2026-05-15
**Status**: Draft
**Input**: User description: "Reconcile the existing Decision Register work against current repo truth before starting any new Decision Register feature work. Do not start a Greenfield Decision Register rebuild; determine whether Decision Register is done enough or needs one narrow 307 follow-up."
## Spec Candidate Check *(mandatory - SPEC-GATE-001)*
- **Problem**: Spec 305 found that Decision Register runtime and tests already exist under and around Spec 265, while product roadmap and candidate documents still describe Decision Register as a future or missing productization slice.
- **Today's failure**: Without a repo-based reconciliation, the next productization step can duplicate Spec 265, overstate remaining gaps, understate implemented truth, or choose the wrong 307 follow-up.
- **User-visible improvement**: Product planning gets a single truth artifact that states what Decision Register already implements, what tests prove, which product docs drift, and whether only a narrow follow-up is needed.
- **Smallest enterprise-capable version**: One docs-first reconciliation artifact at `specs/306-decision-register-reconciliation/decision-register-reconciliation.md`, plus minimal product-doc sync only if stale docs are proven. No runtime code changes.
- **Explicit non-goals**: No new Decision Register runtime, no replacement approval workflow, no migrations, no models, no services, no Filament resources/pages, no tests, no routes, no policies, no jobs, no notifications, no UI assets, no PSA integration, no customer portal, no Review Pack redesign, no OperationRun lifecycle changes, and no broad roadmap rewrite.
- **Permanent complexity imported**: One Spec Kit package and one reconciliation artifact. Product docs may receive small truth-sync edits if drift is repo-verified. No application complexity is introduced.
- **Why now**: Spec 305 explicitly concluded that a fresh `Decision Register & Approval Workflow v1` spec is a NO-GO unless Spec 265/runtime truth is reconciled first.
- **Why not local**: A local note would not update the Spec Kit audit trail, would not force focused test validation, and would not create a reviewable product-truth record before the next spec decision.
- **Approval class**: Cleanup.
- **Red flags triggered**: Duplicate feature-work risk, stale product docs, broad cross-surface audit scope. These are mitigated by audit-only scope, fixed output structure, explicit status vocabulary, and a ban on runtime changes.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 2 | Produktnaehe: 2 | Wiederverwendung: 2 | **Gesamt: 12/12**
- **Decision**: approve.
## Spec Scope Fields *(mandatory)*
- **Scope**: canonical-view.
- **Primary Routes**: No route changes. The audit inspects existing routes and surfaces only, including the Decision Register page route, Governance Inbox, FindingException surfaces, evidence/report/review links, and OperationRun links where repo-real.
- **Data Ownership**: No data changes. The audit reviews existing workspace/environment/tenant-owned records only: `FindingException`, `FindingExceptionDecision`, `FindingExceptionEvidenceReference`, `EvidenceSnapshot`, `StoredReport`, `EnvironmentReview`, `ReviewPack`, `OperationRun`, `AuditLog`, and related runtime truth if present.
- **RBAC**: No RBAC changes. The audit records existing capability, policy, workspace isolation, and environment isolation evidence.
For canonical-view specs:
- **Default filter behavior when tenant-context is active**: N/A - audit-only. Existing filter behavior is inspected as evidence.
- **Explicit entitlement checks preventing cross-tenant leakage**: N/A - audit-only. Existing tests and runtime checks are reviewed and classified.
## Cross-Cutting / Shared Pattern Reuse *(mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write `N/A - no shared interaction family touched`)*
- **Cross-cutting feature?**: yes, audit-only.
- **Interaction class(es)**: governance navigation, decision register, governance inbox, finding-exception detail, evidence/report links, review/review-pack links, OperationRun links, RBAC/capability evidence, audit/event evidence, and product documentation truth.
- **Systems touched**: Spec Kit artifacts under `specs/306-decision-register-reconciliation/` and, if drift is confirmed during implementation, minimal product docs under `docs/product/`.
- **Existing pattern(s) to extend**: Spec Kit audit-artifact pattern from Spec 305 and repo-based truth classification in product docs.
- **Shared contract / presenter / builder / renderer to reuse**: No runtime contract is changed. The audit may cite existing builders, pages, policies, capabilities, link helpers, and test families.
- **Why the existing shared path is sufficient or insufficient**: Existing runtime paths are sufficient for evidence gathering; this spec only records and synchronizes truth.
- **Allowed deviation and why**: none.
- **Consistency impact**: The artifact must use the required status vocabulary and must not introduce new Greenfield Decision Register terminology.
- **Review focus**: Confirm that 306 reconciles Spec 265/runtime/docs truth and does not implement or specify a broad new Decision Register.
## OperationRun UX Impact *(mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an `OperationRun`; otherwise write `N/A - no OperationRun start or link semantics touched`)*
- **Touches OperationRun start/completion/link UX?**: no runtime change. Existing OperationRun links are inspected as evidence only.
- **Shared OperationRun UX contract/layer reused**: N/A.
- **Delegated start/completion UX behaviors**: N/A.
- **Local surface-owned behavior that remains**: none.
- **Queued DB-notification policy**: N/A.
- **Terminal notification path**: N/A.
- **Exception required?**: none.
## Provider Boundary / Platform Core Check *(mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write `N/A - no shared provider/platform boundary touched`)*
- **Shared provider/platform boundary touched?**: no.
- **Boundary classification**: N/A.
- **Seams affected**: none.
- **Neutral platform terms preserved or introduced**: N/A.
- **Provider-specific semantics retained and why**: none.
- **Why this does not deepen provider coupling accidentally**: The work is documentation-only and audits existing repo truth.
- **Follow-up path**: none.
## UI / Surface Guardrail Impact *(mandatory when operator-facing surfaces are changed; otherwise write `N/A`)*
| Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / `N/A` Note |
|---|---|---|---|---|---|---|
| Decision Register reconciliation artifact | no | N/A | governance, findings, evidence, review, OperationRun, RBAC, audit evidence only | none | no | `N/A - repository workflow only` |
| Minimal product docs sync, if needed | no runtime surface | N/A | product truth only | none | no | Docs-only status correction if drift is proven |
## Decision-First Surface Role *(mandatory when operator-facing surfaces are changed)*
N/A - no operator-facing surface change.
## Audience-Aware Disclosure *(mandatory when operator-facing surfaces are changed)*
N/A - no operator-facing surface change.
## UI/UX Surface Classification *(mandatory when operator-facing surfaces are changed)*
N/A - no operator-facing surface change.
## Operator Surface Contract *(mandatory when operator-facing surfaces are changed)*
N/A - no operator-facing surface change.
## Proportionality Review *(mandatory when structural complexity is introduced)*
- **New source of truth?**: no runtime source of truth. The reconciliation artifact is a Spec Kit product-truth decision record for planning.
- **New persisted entity/table/artifact?**: yes, documentation artifact only: `decision-register-reconciliation.md`.
- **New abstraction?**: no.
- **New enum/state/reason family?**: no.
- **New cross-domain UI framework/taxonomy?**: no.
- **Current operator problem**: Product planning must decide whether Decision Register is already done enough or needs one narrow 307 follow-up.
- **Existing structure is insufficient because**: Spec 265, runtime, tests, roadmap, candidate docs, and implementation ledger currently disagree or may be stale; a focused reconciliation makes the decision auditable.
- **Narrowest correct implementation**: One docs-only audit artifact, focused validation commands, and minimal docs sync if proven stale.
- **Ownership cost**: Future spec selection must consult the artifact; no runtime maintenance cost.
- **Alternative intentionally rejected**: Starting a broad new Decision Register v1 spec was rejected because Spec 305 already found repo evidence for existing Decision Register runtime/tests.
- **Release truth**: Current-release preparation and product-truth alignment.
### Compatibility posture
This feature assumes a pre-production environment.
Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope. The work does not alter runtime data or behavior.
## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)*
- **Test purpose / classification**: Existing Unit and Feature validation evidence only. No new tests.
- **Validation lane(s)**: confidence via focused existing tests; docs-only whitespace validation via `git diff --check`.
- **Why this classification and these lanes are sufficient**: The change is documentation-only. Existing focused tests are run to support claims about current Decision Register, Governance Inbox, FindingException, Evidence/Review, and OperationRun link behavior.
- **New or expanded test families**: none.
- **Fixture / helper cost impact**: none.
- **Heavy-family visibility / justification**: none.
- **Special surface test profile**: N/A for new work; existing Decision Register/Governance tests are cited by path.
- **Standard-native relief or required special coverage**: no new UI. The audit records existing UI/test evidence.
- **Reviewer handoff**: Review `decision-register-reconciliation.md`, confirm no runtime/test files changed, and rerun the focused commands listed in the artifact if needed.
- **Budget / baseline / trend impact**: none.
- **Escalation needed**: none.
- **Active feature PR close-out entry**: Guardrail.
- **Planned validation commands**:
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/GovernanceDecisions/GovernanceDecisionRegisterBuilderTest.php tests/Unit/Support/GovernanceInbox/GovernanceInboxSectionBuilderTest.php tests/Feature/Governance/DecisionRegisterPageTest.php tests/Feature/Governance/DecisionRegisterAuthorizationTest.php tests/Feature/Governance/GovernanceInboxPageTest.php tests/Feature/Governance/GovernanceInboxAuthorizationTest.php tests/Feature/Findings/FindingExceptionDecisionRegisterNavigationTest.php tests/Feature/Findings/FindingExceptionDetailDecisionSummaryTest.php tests/Feature/Findings/FindingExceptionDecisionRegisterBoundariesTest.php`
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Evidence/EvidenceSnapshotResourceTest.php tests/Feature/Evidence/EvidenceSnapshotAuditLogTest.php tests/Feature/EnvironmentReview/EnvironmentReviewAuditLogTest.php tests/Feature/EnvironmentReview/EnvironmentReviewRegisterTest.php tests/Feature/EnvironmentReview/EnvironmentReviewRegisterRbacTest.php tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php tests/Feature/Reviews/CustomerReviewWorkspaceAuthorizationTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php tests/Feature/Filament/GovernanceArtifacts/GovernanceArtifactDeepLinkContractTest.php`
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php tests/Feature/Operations/LegacyRunRoutesNotFoundTest.php tests/Feature/ProviderConnections/LegacyRedirectTest.php tests/Feature/RequiredPermissions/RequiredPermissionsLegacyRouteTest.php tests/Feature/Guards/ManagedEnvironmentCanonicalRouteContractTest.php tests/Feature/Filament/PolicyVersionResolvedReferenceLinksTest.php`
- `git diff --check`
- `git status --short --branch`
## Summary
Reconcile the existing Decision Register work against current repo truth before any new Decision Register feature work begins.
Spec 305 concluded that TenantPilot is broadly feature-ready after Specs 301-304, but with an important condition: Decision Register & Approval Workflow v1 must not be started as a fresh Greenfield feature because Spec 265 plus Decision Register runtime/tests already exist.
This spec resolves that condition by determining:
- what Spec 265 already defined
- what runtime already implements
- what tests already prove
- what product docs currently understate, overstate, or misclassify
- whether Decision Register is `foundation-only`, `partial productization`, `near sellable`, `sellable`, or `not implemented`
- what the narrowest next follow-up should be, if any
## Core Decision
Do not create a new broad `Decision Register v1` spec unless repo truth proves that existing Spec 265/runtime is not usable.
Default posture:
- reconcile first
- document truth
- update stale product docs minimally
- identify one narrow follow-up only if needed
## Scope Boundary
This is an audit/reconciliation spec. It must not implement application runtime.
Allowed changes during implementation:
- Spec Kit artifacts in `specs/306-decision-register-reconciliation/`
- `specs/306-decision-register-reconciliation/decision-register-reconciliation.md`
- minimal product-doc sync in `docs/product/spec-candidates.md`, `docs/product/implementation-ledger.md`, or `docs/product/roadmap.md` only if stale docs are proven
Forbidden changes:
- migrations
- models
- services
- Filament pages/resources
- tests
- routes
- providers
- UI assets
- policies
- jobs
- queues
- notifications
- runtime behavior
## Output Artifact
Create:
```text
specs/306-decision-register-reconciliation/decision-register-reconciliation.md
```
The artifact must use this structure:
```md
# Decision Register Reconciliation
## Executive Conclusion
## Scope Boundary
## Inputs Reviewed
## Spec 265 Summary
## Runtime Evidence Matrix
## Test Evidence Matrix
## Product Docs Drift
## Capability Matrix
## Sellability Classification
## Open Gaps
## Recommended Next Action
## Candidate Follow-ups
## Validation Evidence
## Close-Out Notes
```
## Required Status Language
Use only these status terms where possible:
- `repo-verified`
- `implemented`
- `foundation-only`
- `partial productization`
- `near sellable`
- `sellable`
- `productization gap`
- `not implemented`
- `stale docs`
- `blocked`
- `not applicable`
- `follow-up required`
Do not present assumptions as facts. Every implementation claim must have repo evidence.
## Reconciliation Questions
### Q1 - What did Spec 265 actually promise?
Review Spec 265 and classify its scope:
- data model
- UI surface
- governance inbox integration
- finding integration
- approval semantics
- closure semantics
- evidence links
- OperationRun links
- RBAC/capabilities
- audit/event semantics
- tests
- docs
### Q2 - What exists in runtime?
Inspect current code for Decision Register implementation and classify each capability as:
- `implemented`
- `partial productization`
- `foundation-only`
- `not implemented`
- `blocked`
### Q3 - What do tests prove?
List focused tests and what they prove. Test files existing does not automatically mean behavior is correct; use test names, assertions, and executed validation output.
### Q4 - What is stale in product docs?
Check:
- `docs/product/spec-candidates.md`
- `docs/product/implementation-ledger.md`
- `docs/product/roadmap.md`
Classify whether Decision Register is missing, misclassified as future-only, duplicated as a candidate, understated, overstated, or correctly represented.
### Q5 - Is Decision Register ready for the next feature layer?
Classify the current state as one of:
- no further feature work needed now
- product docs only
- narrow follow-up required
- broader feature follow-up required
- not ready / blocker
### Q6 - What should 307 be?
Recommend one next step:
- a Decision Register follow-up
- another productization feature
- docs-only synchronization
- blocker repair
## User Scenarios & Testing *(mandatory)*
### User Story 1 - Reconcile Spec 265 Against Repo Truth (Priority: P1)
As a productization owner, I need Spec 265 compared to runtime and tests so I can avoid duplicate Decision Register work.
**Why this priority**: This is the core risk identified by Spec 305.
**Independent Test**: Review `decision-register-reconciliation.md` and confirm it includes a Spec 265 summary, runtime evidence matrix, test evidence matrix, and caveats for unsupported claims.
**Acceptance Scenarios**:
1. **Given** Spec 265 and current runtime exist, **When** the audit is complete, **Then** every implementation claim has repo evidence.
2. **Given** a capability is not proven by runtime or tests, **When** the audit classifies it, **Then** the caveat is explicit and not stated as implemented.
---
### User Story 2 - Correct Product-Doc Drift Minimally (Priority: P1)
As a roadmap maintainer, I need product docs to reflect Decision Register repo truth without rewriting roadmap history.
**Why this priority**: Stale docs can cause the wrong 307 selection.
**Independent Test**: Inspect the product docs drift section and the git diff. Confirm docs are updated only if stale and only with small status-sync edits.
**Acceptance Scenarios**:
1. **Given** product docs list Decision Register as open Greenfield work while runtime exists, **When** stale docs are confirmed, **Then** docs are updated minimally to mark reconciliation or narrow follow-up status.
2. **Given** a product doc is already accurate, **When** the audit is complete, **Then** that doc is not rewritten.
---
### User Story 3 - Decide The Narrowest Next Step (Priority: P1)
As the next-spec owner, I need a clear answer on whether 307 should be a Decision Register follow-up or a different productization feature.
**Why this priority**: The user explicitly requested not to ask broadly whether the product is feature-ready again after 306.
**Independent Test**: Review the recommended next action and candidate follow-ups. Confirm exactly one next-action category is selected.
**Acceptance Scenarios**:
1. **Given** Decision Register is classified, **When** the audit closes, **Then** it recommends exactly one of `no further feature work needed now`, `product docs only`, `narrow follow-up spec required`, `broader feature follow-up required`, or `not ready / blocker`.
2. **Given** a follow-up is needed, **When** the audit names it, **Then** it is narrow and does not duplicate Spec 265.
### Edge Cases
- A test path listed in Spec 305 may not exist anymore; document it as `not applicable` rather than inventing coverage.
- A product doc may understate runtime truth but still preserve useful candidate history; keep the history and add a status correction instead of deleting it.
- Runtime may implement a page but not customer-safe consumption; classify customer readiness separately.
- Approval or closure may exist as status/history but not as a capability-gated workflow; classify semantics precisely.
## Requirements *(mandatory)*
### Functional Requirements
- **FR-001**: The audit MUST inspect Spec 265 and summarize intended scope, completed tasks if present, incomplete tasks if present, acceptance criteria, explicit non-goals, dependencies, tests listed, runtime expectations, and close-out history if present.
- **FR-002**: The audit MUST inspect current runtime for Decision Register related code, including models, migrations, services/builders, Filament pages/resources, policies, capability definitions, navigation, integration points, event/audit behavior, Governance Inbox integrations, FindingException integrations, Evidence/StoredReport links, OperationRun links, and Review/Review Pack links where present.
- **FR-003**: The audit MUST inspect and run focused existing tests related to Decision Register builder, Decision Register page, Decision Register authorization, Governance Inbox integration, FindingException decision integration, decision boundaries, and relevant Evidence/Review/OperationRun links if present.
- **FR-004**: The audit artifact MUST include a complete capability matrix with columns: Capability, Status, Repo evidence, Test evidence, Caveat, Recommended action.
- **FR-005**: The audit MUST classify Decision Register as exactly one of `foundation-only`, `partial productization`, `near sellable`, `sellable`, or `not implemented`.
- **FR-006**: The audit MUST inspect product docs and classify drift as accurate, stale, understate repo truth, overstate repo truth, or duplicate candidate risk.
- **FR-007**: If product docs are stale, the implementation MUST update only `docs/product/spec-candidates.md`, `docs/product/implementation-ledger.md`, or `docs/product/roadmap.md` minimally and truthfully.
- **FR-008**: The audit MUST recommend exactly one next action category: `no further feature work needed now`, `product docs only`, `narrow follow-up spec required`, `broader feature follow-up required`, or `not ready / blocker`.
- **FR-009**: The implementation MUST NOT change application runtime, migrations, models, services, Filament pages/resources, tests, routes, providers, UI assets, policies, jobs, queues, notifications, or behavior.
- **FR-010**: The audit MUST run focused validation commands and record results in the reconciliation artifact.
### Capability Matrix Minimum Rows
The capability matrix MUST include at least:
- Decision Register page
- Decision detail or summary surface
- decision source linkage
- FindingException integration
- Governance Inbox integration
- owner/assignment semantics
- due state semantics
- approval semantics
- closure semantics
- audit/event semantics
- RBAC/capability enforcement
- workspace isolation
- environment isolation
- evidence/report linkage
- OperationRun linkage
- review/review-pack linkage
- customer-safe consumption readiness
- product docs alignment
### Product Docs Sync Rules
For `docs/product/spec-candidates.md`:
- If Decision Register is still listed as open Greenfield candidate, change it to one of: reconciled with Spec 265, follow-up required, moved out of Greenfield scope, or narrow productization follow-up pending.
- Keep history.
- Do not silently delete.
For `docs/product/implementation-ledger.md`:
- Add or adjust a truth entry if repo evidence proves Decision Register foundation/runtime exists.
- Classify maturity accurately.
- Document caveats.
- Do not overstate sellability.
For `docs/product/roadmap.md`:
- Only touch if it currently misleads sequencing.
- Allowed change: one small note that Decision Register is not Greenfield and next work should be reconciliation/follow-up.
- Avoid broad roadmap reprioritization.
## Success Criteria *(mandatory)*
- **SC-001**: `decision-register-reconciliation.md` exists and follows the required structure.
- **SC-002**: Spec 265 is summarized against current repo truth.
- **SC-003**: Decision Register runtime components are listed with repo evidence.
- **SC-004**: Relevant tests are listed with what they prove and validation output.
- **SC-005**: Capability matrix covers UI, source links, governance inbox, finding integration, approval, closure, evidence, OperationRun, review, RBAC, audit, and customer-safe readiness.
- **SC-006**: The artifact states exactly one sellability classification.
- **SC-007**: Product docs drift is assessed.
- **SC-008**: Stale product docs are updated minimally and truthfully if needed.
- **SC-009**: No runtime files are changed.
- **SC-010**: Focused validation results are recorded.
- **SC-011**: The next step is clear and narrow.
- **SC-012**: Any proposed follow-up spec does not duplicate Spec 265.
- **SC-013**: The artifact explicitly states that a broad new Decision Register v1 spec should not be created unless the audit proves Spec 265/runtime unusable.
- **SC-014**: `git diff --check` passes.
## Assumptions
- Spec 265, Spec 305, runtime code, tests, and product docs are authoritative inputs.
- User-provided Spec 306 content is the selected candidate; no alternate next-best candidate selection is needed for this prep.
- Product docs may be stale, but the implementation must prove drift before editing them.
- Existing focused tests may require Sail to be running; if validation cannot run, the artifact must record the command, reason, and residual risk.
## Risks
- **Risk: Recreating Decision Register as Greenfield**. Mitigation: Spec 306 explicitly forbids Greenfield rebuild and makes Spec 265/runtime the baseline.
- **Risk: Overstating sellability**. Mitigation: Required status language separates implemented foundation from sellable product surface and customer-safe readiness.
- **Risk: Understating repo truth**. Mitigation: Runtime and tests are reconciled before product docs are updated.
- **Risk: Docs sync becomes roadmap rewrite**. Mitigation: Only Decision Register references may be corrected, and history must be preserved.
- **Risk: Audit becomes implementation**. Mitigation: Runtime files, tests, routes, migrations, services, policies, assets, and jobs are explicitly forbidden.
## Candidate Selection Rationale
- **Selected candidate**: Decision Register Reconciliation & Productization Follow-up.
- **Source location**: Directly provided by the user on 2026-05-15 after Spec 305 close-out.
- **Why selected**: Spec 305 made reconciliation the next required gate before deciding whether 307 is a small Decision Register follow-up or another productization feature.
- **Why close alternatives were deferred**:
- A fresh `Decision Register & Approval Workflow v1` is deferred because Spec 265 and runtime/tests already exist.
- `Governance Artifact Lifecycle & Retention v1`, `Billing & Subscription Truth Layer v1`, `Stored Reports Surface v1`, and other productization candidates are deferred until Decision Register truth is reconciled.
- A broad roadmap rewrite is deferred because the user requested only the Decision Register reconciliation decision.
- **Completed-spec guardrail result**: Spec 265 is related and appears implemented/closed by completed task markers and Spec 305 runtime/test evidence; it is context only and must not be rewritten.
- **Smallest viable implementation slice**: Docs-only reconciliation artifact, focused validation, minimal product-doc sync if stale, and one recommended 307 path.
## Follow-up Candidate Naming Rules
If a follow-up is needed, do not name it broadly as:
- `Decision Register v1`
- `Decision-Based Governance Inbox v1`
- `Governance Workflow Platform`
- `Approval Engine`
Prefer narrow names such as:
- `decision-register-approval-closure-hardening`
- `decision-register-evidence-operationrun-link-polish`
- `decision-register-review-pack-inclusion`
- `decision-register-customer-safe-summary`
- `decision-register-docs-ledger-sync`
- `stored-reports-surface-productization`
- `governance-artifact-lifecycle-retention`

163
specs/306-decision-register-reconciliation/tasks.md Normal file
View File

@ -0,0 +1,163 @@
---
description: "Task list for Decision Register Reconciliation & Productization Follow-up"
---
# Tasks: Decision Register Reconciliation & Productization Follow-up
**Input**: Design documents from `specs/306-decision-register-reconciliation/`
**Prerequisites**: `specs/306-decision-register-reconciliation/spec.md`, `specs/306-decision-register-reconciliation/plan.md`, `specs/306-decision-register-reconciliation/checklists/requirements.md`
**Tests**: No tests are created or edited. Existing focused tests are inspected and run for validation evidence only.
**Operations**: No `OperationRun`, queue, job, notification, Graph call, or remote action is introduced.
**RBAC**: No RBAC changes. Existing capabilities, policies, workspace isolation, and environment isolation are inspected and classified.
**Filament / Panel Guardrails**: Filament remains v5 on Livewire v4. Provider registration remains unchanged in `apps/platform/bootstrap/providers.php`. No globally searchable resource, destructive action, panel, route, or asset is added.
**Organization**: Tasks are grouped by audit phase. Every task is docs-only or read-only validation unless product-doc drift is proven and a minimal docs sync is explicitly performed.
## Test Governance Checklist
- [x] Lane assignment stays existing focused `Unit` and `Feature` tests plus docs whitespace validation.
- [x] No new or changed test families are introduced.
- [x] No shared helpers, factories, seeds, fixtures, or context defaults are changed.
- [x] Planned validation commands cover Decision Register/Governance/Findings plus supporting Evidence/Review/OperationRun links where paths exist.
- [x] Any missing test path is recorded as `not applicable`, not treated as covered.
- [x] Any validation failure is recorded in the artifact with residual risk; runtime/test fixes are out of scope.
## Phase 1: Setup
**Purpose**: Confirm the repo state and gather the required context before the audit begins.
- [x] T001 Confirm current git branch and clean starting state before implementing 306.
- [x] T002 Read `AGENTS.md`, `.specify/memory/constitution.md`, Spec Kit templates/scripts, and this Spec 306 package.
- [x] T003 Review `specs/305-feature-readiness-gate-audit/spec.md` and `specs/305-feature-readiness-gate-audit/feature-readiness-audit.md` to carry forward the no-Greenfield Decision Register condition.
---
## Phase 2: Spec 265 Reconciliation
**Purpose**: Establish what Spec 265 actually promised and whether its package appears completed, partial, or still open.
- [x] T004 Inspect `specs/265-decision-register-approval/spec.md`, `specs/265-decision-register-approval/plan.md`, `specs/265-decision-register-approval/tasks.md`, `specs/265-decision-register-approval/checklists/requirements.md`, and any close-out notes or related artifacts.
- [x] T005 Record Spec 265 intended scope, completed tasks, incomplete tasks if any, acceptance criteria, explicit non-goals, dependencies, tests listed, runtime expectations, and close-out history if present.
---
## Phase 3: Runtime Inventory
**Purpose**: Inventory current Decision Register runtime without changing it.
- [x] T006 Search the repo for Decision Register related runtime using focused searches such as `rg -n "GovernanceDecision|DecisionRegister|decision register|governance decision|approval|closure" apps/platform/app apps/platform/database apps/platform/tests`.
- [x] T007 Inspect repo-verified models, migrations, services/builders, Filament pages/resources, policies, capability definitions, navigation entries, Governance Inbox integrations, FindingException integrations, Evidence/StoredReport links, OperationRun links, review/review-pack links, and audit/event behavior.
- [x] T008 Record confirmed runtime paths and classify each capability as `implemented`, `partial productization`, `foundation-only`, `not implemented`, or `blocked`.
---
## Phase 4: Test Inventory and Validation
**Purpose**: Determine what focused tests prove, then run existing validation commands where paths exist.
- [x] T009 Inspect relevant tests, including Decision Register builder, Governance Inbox builder, Decision Register page/authorization, Governance Inbox page/authorization, FindingException decision navigation, detail summary, and boundaries.
- [x] T010 Run the focused Decision Register lane:
```bash
cd apps/platform && ./vendor/bin/sail artisan test --compact \
tests/Unit/Support/GovernanceDecisions/GovernanceDecisionRegisterBuilderTest.php \
tests/Unit/Support/GovernanceInbox/GovernanceInboxSectionBuilderTest.php \
tests/Feature/Governance/DecisionRegisterPageTest.php \
tests/Feature/Governance/DecisionRegisterAuthorizationTest.php \
tests/Feature/Governance/GovernanceInboxPageTest.php \
tests/Feature/Governance/GovernanceInboxAuthorizationTest.php \
tests/Feature/Findings/FindingExceptionDecisionRegisterNavigationTest.php \
tests/Feature/Findings/FindingExceptionDetailDecisionSummaryTest.php \
tests/Feature/Findings/FindingExceptionDecisionRegisterBoundariesTest.php
```
- [x] T011 Run supporting artifact/review/link tests if paths exist:
```bash
cd apps/platform && ./vendor/bin/sail artisan test --compact \
tests/Feature/Evidence/EvidenceSnapshotResourceTest.php \
tests/Feature/Evidence/EvidenceSnapshotAuditLogTest.php \
tests/Feature/EnvironmentReview/EnvironmentReviewAuditLogTest.php \
tests/Feature/EnvironmentReview/EnvironmentReviewRegisterTest.php \
tests/Feature/EnvironmentReview/EnvironmentReviewRegisterRbacTest.php \
tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php \
tests/Feature/Reviews/CustomerReviewWorkspaceAuthorizationTest.php \
tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php \
tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php \
tests/Feature/Filament/GovernanceArtifacts/GovernanceArtifactDeepLinkContractTest.php
```
- [x] T012 Run OperationRun/link guard tests if paths exist:
```bash
cd apps/platform && ./vendor/bin/sail artisan test --compact \
tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php \
tests/Feature/Operations/LegacyRunRoutesNotFoundTest.php \
tests/Feature/ProviderConnections/LegacyRedirectTest.php \
tests/Feature/RequiredPermissions/RequiredPermissionsLegacyRouteTest.php \
tests/Feature/Guards/ManagedEnvironmentCanonicalRouteContractTest.php \
tests/Feature/Filament/PolicyVersionResolvedReferenceLinksTest.php
```
---
## Phase 5: Product Docs Drift Check
**Purpose**: Determine whether Decision Register is missing, duplicated, understated, overstated, or correctly represented in product docs.
- [x] T013 Review `docs/product/spec-candidates.md`, `docs/product/implementation-ledger.md`, and `docs/product/roadmap.md` for Decision Register references.
- [x] T014 Classify each product doc as accurate, stale, understate repo truth, overstate repo truth, or duplicate candidate risk.
- [x] T015 If stale docs are proven, update only the minimal Decision Register text in the allowed product docs while preserving history and avoiding broad roadmap rewrite.
---
## Phase 6: Reconciliation Artifact
**Purpose**: Produce the required audit artifact and recommendation.
- [x] T016 Create `specs/306-decision-register-reconciliation/decision-register-reconciliation.md` with the required structure:
```text
Executive Conclusion
Scope Boundary
Inputs Reviewed
Spec 265 Summary
Runtime Evidence Matrix
Test Evidence Matrix
Product Docs Drift
Capability Matrix
Sellability Classification
Open Gaps
Recommended Next Action
Candidate Follow-ups
Validation Evidence
Close-Out Notes
```
- [x] T017 Add the complete capability matrix covering UI, source links, governance inbox, finding integration, owner/assignment, due state, approval, closure, audit, RBAC, workspace isolation, environment isolation, evidence/report, OperationRun, review/review-pack, customer-safe readiness, and product docs alignment.
- [x] T018 Choose exactly one sellability classification: `foundation-only`, `partial productization`, `near sellable`, `sellable`, or `not implemented`.
- [x] T019 Recommend exactly one next action category: `no further feature work needed now`, `product docs only`, `narrow follow-up spec required`, `broader feature follow-up required`, or `not ready / blocker`.
- [x] T020 If a follow-up is required, name one narrow primary follow-up and list adjacent candidates separately without hiding them in scope.
- [x] T021 Explicitly state that a broad new Decision Register v1 spec should not be created unless the audit proves Spec 265/runtime unusable.
---
## Phase 7: Scope and Whitespace Validation
**Purpose**: Confirm 306 stayed docs-only and records validation evidence.
- [x] T022 Run `git status --short --branch` and confirm changed files are limited to `specs/306-decision-register-reconciliation/` plus minimal allowed product-doc sync if needed.
- [x] T023 Confirm no files changed under `apps/platform/app`, `apps/platform/database`, `apps/platform/routes`, `apps/platform/resources`, `apps/platform/tests`, runtime config, providers, jobs, policies, services, UI assets, or migrations.
- [x] T024 Run `git diff --check`.
- [x] T025 Update `decision-register-reconciliation.md` close-out notes with files created, product docs changed if any, runtime files changed as none, Spec 265 summary, runtime classification, sellability classification, recommended next action, focused test results, `git diff --check` result, caveats, and whether 307 should be a Decision Register follow-up or a different productization feature.
- [x] T026 Mark completed implementation tasks in this file only after the corresponding audit work is actually done.
## Non-Goals Checklist
- [x] No runtime code changes.
- [x] No migrations.
- [x] No models, services, jobs, policies, routes, providers, Filament pages/resources, UI assets, or notifications changed.
- [x] No tests created or modified.
- [x] No broad Decision Register v1 replacement started.
- [x] No broad roadmap rewrite.
- [x] No stale product-doc history deleted silently.