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

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:

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

The artifact must use this structure:

# 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