ahmido
ba0b6ec07e
## 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
164 lines
9.9 KiB
Markdown
164 lines
9.9 KiB
Markdown
---
|
|
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.
|