# 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.