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](./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.