# 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.