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