ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
15b21c3080
TenantAtlas/specs/201-enforcement-review-guardrails/tasks.md
ahmido 15b21c3080
Some checks failed
Main Confidence / confidence (push) Failing after 44s
Details
spec: finalize enforcement review guardrails workflow (#250) 
## Summary
- add the full Spec 201 artifact set for enforcement and review guardrails
- update the SpecKit workflow surfaces to carry UI/surface guardrail classification, handling modes, proof depth, and close-out targeting
- align the operator UX standards reference and agent context with the new guardrail workflow

## Validation
- completed cross-artifact consistency analysis for spec, plan, tasks, research, data model, contracts, and quickstart
- recorded the low-impact workflow path at `00:48` and the representative guarded review at `02:34`
- no Pest or runtime test suite was run because this is a docs/workflow-only feature
- integrated browser smoke on the tenant dashboard could not complete because tenant-scoped unauthenticated navigation currently redirects to `/admin/t/login`, which returns `404 Not Found`

## Filament Notes
- Livewire v4.0+ compliance is unchanged
- provider registration remains in `bootstrap/providers.php`
- no globally searchable resources were added or modified
- no destructive runtime actions were introduced or changed
- no asset strategy changes were made; existing `filament:assets` deployment behavior remains unchanged

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #250
2026-04-18 22:46:06 +00:00

188 lines
14 KiB
Markdown
Raw Blame History

# Tasks: Enforcement & Review Guardrails
**Input**: Design documents from `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/201-enforcement-review-guardrails/`
**Prerequisites**: `plan.md` (required), `spec.md` (required), `research.md`, `data-model.md`, `contracts/`, `quickstart.md`
**Tests**: Not required. This feature is docs and workflow only, so validation is by representative low-impact and guarded-case walkthroughs, cross-artifact consistency review, and recording the outcomes in the active spec artifacts.
**Organization**: Tasks are grouped by user story so each story can be implemented and validated independently where possible.
## Phase 1: Setup (Shared Context)
**Purpose**: Freeze the real workflow surfaces and the exact implementation scope before editing templates or guidance.
- [X] T001 Audit `specs/201-enforcement-review-guardrails/spec.md`, `specs/201-enforcement-review-guardrails/plan.md`, `specs/201-enforcement-review-guardrails/research.md`, `specs/201-enforcement-review-guardrails/data-model.md`, `specs/201-enforcement-review-guardrails/quickstart.md`, `.specify/templates/spec-template.md`, `.specify/templates/plan-template.md`, `.specify/templates/tasks-template.md`, `.specify/templates/checklist-template.md`, `.specify/README.md`, and `docs/ui/operator-ux-surface-standards.md` against Specs 196 through 200 to confirm the exact guardrail gaps and optional wording-alignment scope
---
## Phase 2: Foundational (Blocking Stabilization Prerequisites)
**Purpose**: Reconcile and stabilize the shared guardrail vocabulary and structured contracts that every later template and checklist update depends on.
**Critical**: No user story work should begin until this phase is complete.
- [X] T002 Reconcile and confirm `specs/201-enforcement-review-guardrails/data-model.md` as the stable source for rule mappings, reviewer question set, repository signals, test-guardrail profiles, exception workflow, workflow touchpoints, validation scenarios, and the active feature PR close-out entry that all later workflow surfaces must reuse
- [X] T003 [P] Reconcile `specs/201-enforcement-review-guardrails/contracts/guardrail-governance.schema.json` with the confirmed rule mappings, review outcome classes, repository-signal handling modes, test-guardrail profiles, validation scenarios, and the active feature PR close-out entry from `specs/201-enforcement-review-guardrails/data-model.md`
- [X] T004 [P] Reconcile `specs/201-enforcement-review-guardrails/contracts/guardrail-governance.logical.openapi.yaml` with the confirmed logical flows for spec-impact validation, review classification, repository-signal assessment, test-guardrail resolution, exception assessment, and the active feature PR close-out entry
- [X] T005 [P] Refine `specs/201-enforcement-review-guardrails/quickstart.md` with the canonical low-impact path, the representative fake-native/shared-family/state-layer/exception walkthroughs, the timing and duplicate-prompt validation expectations, and the explicit first-pass deferral list for grep/lint/CI hardening
**Checkpoint**: The shared vocabulary, contracts, and validation scenarios are stable enough for story-specific workflow changes.
---
## Phase 3: User Story 1 - Reviewers Classify Drift Early (Priority: P1) 🎯 MVP
**Goal**: Give reviewers one fixed checklist and outcome model that catches fake-native drift, host drift, hidden exceptions, and shell/page/detail confusion before merge.
**Independent Test**: Apply the finished reviewer workflow to the representative cases from Specs 196 through 200 and confirm the review can reach the intended guardrail outcome without inventing new categories.
### Implementation for User Story 1
- [X] T006 [P] [US1] Update `.specify/templates/checklist-template.md` with the fixed UI/surface guardrail questions, the review outcome classes (`blocker`, `strong-warning`, `documentation-required-exception`, `acceptable-special-case`), and the explicit workflow outcomes (`keep`, `split`, `document-in-feature`, `follow-up-spec`, `reject-or-split`)
- [X] T007 [P] [US1] Update `.specify/README.md` as the reviewer entry point for applying the canonical UI/surface guardrail checklist, handling low-impact `N/A` cases, and interpreting the workflow outcomes consistently
- [X] T008 [US1] Validate the reviewer workflow against `specs/196-hard-filament-nativity-cleanup/spec.md`, `specs/197-shared-detail-contract/spec.md`, `specs/198-monitoring-page-state/spec.md`, `specs/199-global-context-shell-contract/spec.md`, and `specs/200-filament-surface-rules/spec.md`, then record the reached review outcome classes, handling modes, elapsed guarded-review time, duplicate-question notes, and any wording refinements in `specs/201-enforcement-review-guardrails/spec.md` and `specs/201-enforcement-review-guardrails/quickstart.md`
**Checkpoint**: Reviewers can classify the target drift cases early and consistently.
---
## Phase 4: User Story 2 - Authors Declare Native Vs Custom Up Front (Priority: P1)
**Goal**: Make authors capture native/custom classification, state-layer ownership, shared-family relevance, and exception need during spec and plan authoring.
**Independent Test**: Draft a low-impact docs-only path and a UI/surface-changing path through the updated spec and plan prompts and confirm the required classifications are explicit without adding a second workflow.
### Implementation for User Story 2
- [X] T009 [P] [US2] Update `.specify/templates/spec-template.md` so UI/surface-changing specs explicitly capture native/custom classification, state-layer ownership, shared-family relevance, exception need, and low-impact `N/A` handling when no operator-facing surface changes exist
- [X] T010 [P] [US2] Update `.specify/templates/plan-template.md` so planning artifacts explicitly capture guardrail handling modes, repository-signal treatment, required test depth for special surface classes, and the active feature PR close-out entry for exceptions and smoke coverage
- [X] T011 [US2] Validate the authoring flow using a low-impact docs-only scenario limited to `.specify/templates/checklist-template.md` and `.specify/README.md` plus a surface-changing scenario grounded in `specs/200-filament-surface-rules/spec.md`, then record the authoring outcome, low-impact completion time, duplicate-prompt notes, and any prompt refinements in `specs/201-enforcement-review-guardrails/spec.md` and `specs/201-enforcement-review-guardrails/quickstart.md`
**Checkpoint**: Authors can classify surface risk and exception need before implementation begins.
---
## Phase 5: User Story 3 - Maintainers Get Proportionate Signals And Test Triggers (Priority: P2)
**Goal**: Make likely drift visible through repository signals and define which surface classes require special tests or smoke checks without overhardening standard native surfaces.
**Independent Test**: Map the representative drift classes and surface classes to the final signal catalog and test-guardrail matrix, then confirm each one has a clear handling mode or required test profile.
### Implementation for User Story 3
- [X] T012 [P] [US3] Update `.specify/templates/tasks-template.md` so generated task lists carry forward native/custom, state-layer, shared-family, and exception classification into implementation tasks and require repository-signal handling, review classification work, definition-of-done checks, exception documentation, required tests or manual smoke checks, and the active feature PR close-out entry whenever a special surface class is involved
- [X] T013 [P] [US3] Finalize the repository-signal catalog, test-guardrail matrix, standard-native surface relief rule, and first-pass automation deferrals in `specs/201-enforcement-review-guardrails/research.md`, `specs/201-enforcement-review-guardrails/data-model.md`, and `specs/201-enforcement-review-guardrails/quickstart.md`
- [X] T014 [US3] Validate signal and test-trigger handling against `specs/196-hard-filament-nativity-cleanup/spec.md`, `specs/197-shared-detail-contract/spec.md`, `specs/198-monitoring-page-state/spec.md`, `specs/199-global-context-shell-contract/spec.md`, and `specs/200-filament-surface-rules/spec.md`, then record the final handling-mode matrix, required test profiles, standard-native surface relief rule, active feature PR close-out entry, and any wording refinements in `specs/201-enforcement-review-guardrails/spec.md` and `specs/201-enforcement-review-guardrails/quickstart.md`
**Checkpoint**: Maintainers have one proportionate reference for signals, required tests, and deferred hardening.
---
## Phase 6: Polish & Cross-Cutting Concerns
**Purpose**: Reconcile the finished workflow surfaces and remove drift between the templates, guidance, and active feature artifacts.
- [X] T015 [P] Align `.specify/templates/spec-template.md`, `.specify/templates/plan-template.md`, `.specify/templates/tasks-template.md`, `.specify/templates/checklist-template.md`, `.specify/README.md`, `specs/201-enforcement-review-guardrails/spec.md`, and `specs/201-enforcement-review-guardrails/quickstart.md` so the same guardrail vocabulary and workflow outcomes appear once and without contradictory wording
- [X] T016 [P] Add a minimal guardrail workflow cross-reference in `docs/ui/operator-ux-surface-standards.md` only if the finished templates and `.specify/README.md` still need an explicit pointer from operator-UX standards back to the `.specify/` review workflow
- [X] T017 Run the completion checklist in `specs/201-enforcement-review-guardrails/quickstart.md` against `.specify/templates/spec-template.md`, `.specify/templates/plan-template.md`, `.specify/templates/tasks-template.md`, `.specify/templates/checklist-template.md`, `.specify/README.md`, `specs/201-enforcement-review-guardrails/spec.md`, and `specs/201-enforcement-review-guardrails/plan.md`, then record any remaining first-pass automation deferrals, low-impact completion time, representative guarded-review completion time, active feature PR close-out entry targeting, and redundant-prompt findings in `specs/201-enforcement-review-guardrails/quickstart.md`
---
## Dependencies & Execution Order
### Phase Dependencies
- **Setup (Phase 1)**: No dependencies and can start immediately.
- **Foundational (Phase 2)**: Depends on Setup and blocks all user story work.
- **User Story 1 (Phase 3)**: Depends on Foundational and delivers the MVP review workflow.
- **User Story 2 (Phase 4)**: Depends on Foundational and can proceed independently of User Story 1 once the shared guardrail vocabulary is stable.
- **User Story 3 (Phase 5)**: Depends on Foundational and benefits from the live authoring/review surfaces from User Stories 1 and 2 before final validation closes.
- **Polish (Phase 6)**: Depends on all desired user stories being complete.
### User Story Dependencies
- **User Story 1 (P1)**: Can begin immediately after Foundational and is the recommended MVP slice.
- **User Story 2 (P1)**: Can begin immediately after Foundational and delivers an independent authoring workflow improvement.
- **User Story 3 (P2)**: Can begin after Foundational, but its final validation should run after User Stories 1 and 2 have stabilized the workflow surfaces it references.
### Within Each User Story
- Feature-local guardrail vocabulary and contracts must be stable before template wording is finalized.
- Template changes should land before story-specific validation notes are recorded in `spec.md` and `quickstart.md`.
- Validation walkthroughs should complete before closing the corresponding story.
- Cross-artifact cleanup should happen only after all targeted workflow surfaces are updated.
### Parallel Opportunities
- `T003`, `T004`, and `T005` can run in parallel after `T002` reconciles the guardrail vocabulary and the active feature PR close-out entry.
- `T006` and `T007` can run in parallel because they update different reviewer-facing workflow surfaces.
- `T009` and `T010` can run in parallel because they update different authoring surfaces.
- `T012` and `T013` can run in parallel once Foundational work is stable because they touch different implementation surfaces.
- `T015` and `T016` can run in parallel during Polish because they target different files.
---
## Parallel Example: Foundational Work
```bash
# After T002 reconciles the guardrail vocabulary and the active feature PR close-out entry:
Task: "Align specs/201-enforcement-review-guardrails/contracts/guardrail-governance.schema.json"
Task: "Align specs/201-enforcement-review-guardrails/contracts/guardrail-governance.logical.openapi.yaml"
Task: "Update specs/201-enforcement-review-guardrails/quickstart.md"
```
---
## Parallel Example: User Story 1
```bash
# After Foundational is complete:
Task: "Update .specify/templates/checklist-template.md"
Task: "Update .specify/README.md"
```
---
## Parallel Example: User Story 2
```bash
# After Foundational is complete:
Task: "Update .specify/templates/spec-template.md"
Task: "Update .specify/templates/plan-template.md"
```
---
## Implementation Strategy
### MVP First (User Story 1 Only)
1. Complete Phase 1: Setup.
2. Complete Phase 2: Foundational.
3. Complete Phase 3: User Story 1.
4. Validate the representative reviewer cases before continuing.
### Incremental Delivery
1. Lock the shared guardrail vocabulary and contracts first.
2. Deliver the reviewer-facing workflow surfaces.
3. Deliver the authoring prompts for specs and plans.
4. Deliver the maintainer-facing task and signal/test-trigger surfaces.
5. Finish with cross-artifact cleanup and quickstart completion review.
### Parallel Team Strategy
1. One contributor can stabilize the feature-local guardrail vocabulary while another prepares the contract and quickstart updates after the foundational mapping is fixed.
2. Reviewer-facing surfaces in User Story 1 can be updated in parallel once Foundational is done.
3. Spec and plan template work in User Story 2 can be updated in parallel once the same vocabulary is stable.
4. Maintainer-facing task-template updates and final signal/test-trigger refinements can run in parallel late in the workflow.
---
## Notes
- `[P]` tasks operate on different files or independent workflow surfaces and can run in parallel once dependencies are satisfied.
- `[US1]`, `[US2]`, and `[US3]` map tasks directly to the user stories in `spec.md`.
- This feature is docs and workflow only, so validation is recorded in the active spec artifacts rather than by running Pest lanes.
- First-pass repository signals remain report-first and exception-aware; grep/lint/CI hardening stays explicitly deferred unless the implementation proves a smaller workflow surface is insufficient.
Reference in New Issue View Git Blame Copy Permalink