TenantAtlas/specs/306-decision-register-reconciliation/plan.md

Implementation Plan: Decision Register Reconciliation & Productization Follow-up

Branch: 306-decision-register-reconciliation | Date: 2026-05-15 | Spec: 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

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:

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

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)

specs/306-decision-register-reconciliation/
├── spec.md
├── plan.md
├── tasks.md
├── decision-register-reconciliation.md
└── checklists/
    └── requirements.md

Product Docs (conditional)

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.