TenantAtlas/specs/201-enforcement-review-guardrails/plan.md

# Implementation Plan: Enforcement & Review Guardrails

**Branch**: `201-enforcement-review-guardrails` | **Date**: 2026-04-18 | **Spec**: `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/201-enforcement-review-guardrails/spec.md`
**Input**: Feature specification from `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/201-enforcement-review-guardrails/spec.md`

## Summary

Implement Spec 201 by keeping Spec 200 and `.specify/memory/constitution.md` as the normative rule source while operationalizing those rules through the existing SpecKit workflow surfaces: the spec, plan, task, and checklist templates; `.specify/README.md` as the author and reviewer entry point; and the feature-local guardrail artifacts that define review outcomes, repository-signal handling, required test depth, exception workflow, and close-out expectations. The implementation remains repository-governance only: no runtime UI, no CI hard gates in the first pass, and no second handbook or framework outside the current spec-driven flow.

## Technical Context

**Language/Version**: Markdown governance artifacts, JSON Schema plus logical OpenAPI planning contracts, and Bash-backed SpecKit scripts inside a PHP 8.4.15 / Laravel 12 / Filament v5 / Livewire v4 repository  
**Primary Dependencies**: `.specify/memory/constitution.md`, `.specify/templates/spec-template.md`, `.specify/templates/plan-template.md`, `.specify/templates/tasks-template.md`, `.specify/templates/checklist-template.md`, `.specify/README.md`, `docs/ui/operator-ux-surface-standards.md`, and Specs 196 through 200  
**Storage**: Repository-owned markdown and contract artifacts under `.specify/` and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/201-enforcement-review-guardrails/`; no product database persistence  
**Testing**: Document and template validation against low-impact and high-risk UI-governance scenarios, checklist completeness review, and no runtime Pest execution because the feature is docs and workflow only  
**Validation Lanes**: `N/A`  
**Target Platform**: TenantPilot monorepo workflow, SpecKit authoring flow, and Gitea-backed code review for Laravel operator-facing work  
**Project Type**: Monorepo with a Laravel platform app and Astro website, but this feature is scoped strictly to repository governance and authoring/review workflow artifacts  
**Performance Goals**: Keep low-impact UI-governance answers completable in under 1 minute, keep a representative guarded review under 3 minutes, and avoid duplicating the same guardrail question across multiple workflow surfaces  
**Constraints**: No runtime application code changes, no new CI bot or hard blocking grep/lint layer in the first pass, no parallel handbook or governance subsystem, explicit exception paths must remain available, and repository signals must support false-positive escape rather than becoming unconditional blockers  
**Scale/Scope**: One feature-local guardrail pack, four SpecKit templates, one `.specify/README.md` workflow entry point, optional light-touch operator-UX cross-reference only if wording alignment is necessary, and representative validation across low-impact plus the fake-native, shared-family, exception, and state-layer drift classes

### Filament v5 Implementation Notes

- **Livewire v4.0+ compliance**: Preserved. This feature changes repository workflow artifacts only and does not alter the Filament or Livewire runtime stack.
- **Provider registration location**: Unchanged. Existing panel providers remain registered in `bootstrap/providers.php`.
- **Global search rule**: No globally searchable resources are added or modified.
- **Destructive actions**: No runtime destructive actions are introduced. The workflow artifacts added by this feature continue to require explicit exception and confirmation thinking for future operator-facing surfaces, but they do not change current action behavior.
- **Asset strategy**: No panel or shared assets are added. Existing `filament:assets` deployment behavior remains unchanged.
- **Testing plan**: Validate the guardrail model, template prompts, checklist wording, repository-signal handling, exception documentation, and workflow fit against one low-impact docs-only path and representative high-risk UI-surface cases grounded in Specs 196 through 200; no runtime UI, action, or Livewire tests are added by this feature.

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

- Inventory-first: PASS. No inventory, snapshot, or backup product truth changes.
- Read/write separation: PASS. This is repository-only governance work with no end-user mutations.
- Graph contract path: PASS. No Microsoft Graph calls or contract-registry changes.
- Deterministic capabilities: PASS. No capability resolver, policy, or authorization registry changes.
- RBAC-UX, workspace isolation, tenant isolation: PASS. No runtime routes, surfaces, or policy behavior changes.
- Run observability and Ops-UX: PASS. No `OperationRun` lifecycle or monitoring behavior changes.
- Data minimization: PASS. The new artifacts are repository-owned prompts, schemas, and guidance only.
- Test governance (TEST-GOV-001): PASS WITH WORK. The feature is docs-only, so validation lanes remain `N/A`, but the resulting workflow must still define how special UI surface classes trigger extra tests or smoke expectations in future runtime work.
- Proportionality and bloat control: PASS WITH LIMITS. The implementation touches several workflow entry points, but it stays inside the existing authoring and review chain rather than creating a new subsystem.
- UI semantics and few-layers rules: PASS. The plan reuses Spec 200 vocabulary and does not add a new semantic framework or parallel rulebook.
- Filament-native and surface-taxonomy rules: PASS WITH WORK. The workflow artifacts must reuse the exact Spec 200 and constitution vocabulary rather than invent alternative guardrail terms.
- Decision-first and operator-surface rules: PASS. No new runtime surface is introduced; the plan only makes existing review expectations operational.

**Phase 0 Gate Result**: PASS

- The feature stays bounded to repository governance, templates, checklist prompts, and review guidance.
- No new product persistence, runtime routes, Graph seams, or authorization behavior is introduced.
- The operationalization path keeps Spec 200 as the rule source instead of reopening the constitution with a new competing layer.

## Test Governance Check

- **Affected validation lanes**: `N/A`
- **Narrowest proving command(s)**: `N/A`. Validation is document- and workflow-based rather than runtime-lane based.
- **Fixture / helper cost risks**: None directly. The feature exists to force future surface work to expose needed tests and smoke depth, not to introduce new runtime setup.
- **Heavy-family additions or promotions**: None. The intended change is earlier disclosure of required test depth for special surface classes in future specs and reviews.
- **Budget / baseline / trend follow-up**: None directly. The feature must keep docs-only changes answerable with `N/A` while still making future runtime test obligations explicit.
- **Why no dedicated follow-up spec is needed**: Spec 201 is itself the workflow-guardrail feature. Routine upkeep should stay inside ordinary feature specs after rollout unless later automation or hard gating justifies a separate follow-up spec.

## Project Structure

### Documentation (this feature)

```text
specs/201-enforcement-review-guardrails/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   ├── guardrail-governance.schema.json
│   └── guardrail-governance.logical.openapi.yaml
└── tasks.md
```

### Source Code (repository root)

```text
.specify/
├── README.md
├── memory/
│   └── constitution.md
└── templates/
    ├── checklist-template.md
    ├── plan-template.md
    ├── spec-template.md
    └── tasks-template.md

docs/
└── ui/
    └── operator-ux-surface-standards.md

specs/
├── 196-hard-filament-nativity-cleanup/
├── 197-shared-detail-contract/
├── 198-monitoring-page-state/
├── 199-global-context-shell-contract/
├── 200-filament-surface-rules/
└── 201-enforcement-review-guardrails/
```

**Structure Decision**: Keep changes concentrated in the existing workflow surfaces under `.specify/templates/` and `.specify/README.md`, with `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/201-enforcement-review-guardrails/` holding the feature-local catalog and contract artifacts. `.specify/memory/constitution.md`, `docs/ui/operator-ux-surface-standards.md`, and Specs 196 through 200 are primary references; they should only be edited if a minimal wording alignment is required to avoid ambiguity, not as a second implementation surface.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| None | Not applicable | Not applicable |

## Proportionality Review

- **Current operator problem**: The repo now knows what UI and surface drift looks like, but authors and reviewers still lack one repeatable workflow that turns those rules into concrete review questions, reportable repository signals, required test depth, and visible exception handling before merge.
- **Existing structure is insufficient because**: Spec 200 and the constitution define the rule language, but the current spec, plan, task, and checklist surfaces do not yet force authors or reviewers to classify native versus custom work, state layers, shared-family relevance, repository-signal handling, or exception boundaries consistently.
- **Narrowest correct implementation**: Tighten the existing SpecKit templates and `.specify/README.md`, publish a feature-local guardrail catalog with structured contracts, and validate the workflow against representative real repo cases rather than adding bots, CI policy, or a new handbook.
- **Ownership cost created**: The repo must maintain one shared guardrail vocabulary across templates, review checklists, and workflow guidance, plus a small set of structured planning contracts that describe the model.
- **Alternative intentionally rejected**: A new CI-based enforcement system, a separate UI review handbook, or hard blocking grep/lint automation in the first pass, because each would widen process surface and false-positive risk before the workflow itself is proven.
- **Release truth**: Current-release repository truth needed now so Spec 200 does not immediately decay back into “agreed in principle, optional in practice.”

## Phase 0 — Research (complete)

- Output: [research.md](./research.md)
- Resolved key decisions:
  - Keep Spec 200 plus `.specify/memory/constitution.md` as the normative rule source and operationalize through templates and review guidance instead of reopening the rulebook.
  - Reuse the existing workflow entry points under `.specify/templates/` and `.specify/README.md` rather than introducing a new handbook or contributor process.
  - Treat repository signals as report-first and exception-aware in the first pass, with future promotion paths documented but not enforced automatically.
  - Separate guardrail classes from handling modes so the same rule family can be review-only, technically signalable, test-triggering, or exception-bound without unstable vocabulary.
  - Model required test depth by surface contract class rather than by file type or framework.
  - Use logical schema/OpenAPI artifacts as structured planning contracts for the guardrail pack instead of fabricating runtime APIs.
  - Validate the workflow with one low-impact docs-only scenario plus representative fake-native, shared-family, exception, and state-layer scenarios grounded in Specs 196 through 200.

## Phase 1 — Design & Contracts (baseline complete)

- Output: [data-model.md](./data-model.md) formalizes the repository-owned governance entities: rule mappings, review checklist questions, repository signals, test-guardrail profiles, exception workflows, workflow touchpoints, and validation scenarios.
- Output: [contracts/guardrail-governance.schema.json](./contracts/guardrail-governance.schema.json) defines the schema-first planning contract for the complete guardrail pack; it is not a runtime or transport API.
- Output: [contracts/guardrail-governance.logical.openapi.yaml](./contracts/guardrail-governance.logical.openapi.yaml) captures the logical workflow semantics for classifying specs, evaluating review checklists, resolving repository signals, determining test requirements, and assessing exceptions; it is not a public HTTP contract.
- Output: [quickstart.md](./quickstart.md) provides the implementation order, representative validation walkthroughs, and rollout checklist.
- These artifacts are design-complete enough for planning, but Phase 2 implementation work still stabilizes wording, timing checks, close-out targeting, and cross-artifact alignment before template rollout.

### Post-design Constitution Re-check

- PASS: No runtime routes, panels, Graph seams, assets, or authorization planes are introduced.
- PASS: The design keeps Spec 200 and the constitution as the single rule source and uses templates only for operationalization.
- PASS: The workflow surfaces stay inside existing `.specify/` entry points rather than creating a second governance subsystem.
- PASS WITH WORK: Template prompts and checklist items must avoid asking the same classification question redundantly across spec, plan, task, and review surfaces.
- PASS WITH WORK: Repository signals must remain review-triggering and exception-aware in the first pass so legitimate custom surfaces do not become permanent false positives.

## Phase 2 — Implementation Planning

`tasks.md` should cover:

- Auditing the current guardrail-relevant workflow surfaces and mapping the relevant Spec 200 and constitution rule families to review guardrails, repository signals, test triggers, exception handling, and workflow touchpoints.
- Publishing the feature-local guardrail catalog and logical contracts in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/201-enforcement-review-guardrails/` as the implementation's structured design reference.
- Updating `.specify/templates/spec-template.md` so UI and surface-relevant specs explicitly capture native versus custom classification, state-layer ownership, shared-family relevance, exception need, and low-impact `N/A` handling where no operator-facing surface changes exist.
- Updating `.specify/templates/plan-template.md` so planning surfaces explicitly capture guardrail handling modes, planned repository-signal treatment, required test depth for special surface classes, and the active feature PR close-out entry as the close-out note target for exceptions and smoke coverage.
- Updating `.specify/templates/tasks-template.md` so task generation carries forward native/custom, state-layer, shared-family, and exception classification into implementation tasks and requires review classification work, definition-of-done checks, exception documentation, required tests or smoke checks, and the active feature PR close-out entry whenever a special surface class is involved.
- Updating `.specify/templates/checklist-template.md` as the canonical review-checklist surface so reviewers can apply the fixed question set and end with both a guardrail outcome class and an explicit workflow outcome such as `keep`, `split`, `document-in-feature`, `follow-up-spec`, or `reject-or-split`.
- Updating `.specify/README.md` with a concise author and reviewer entry guide that explains low-impact `N/A` handling, review-stop expectations, and when exception spread or structural drift requires escalation.
- Touching `docs/ui/operator-ux-surface-standards.md` only if one minimal cross-reference is needed to point template users back to the guardrail workflow without duplicating the rules.
- Validating the updated workflow against a low-impact docs-only change plus representative fake-native, shared-family, exception, and shell/page/detail state scenarios derived from Specs 196 through 200.
- Recording explicit first-pass deferrals for grep/lint/CI hardening so later automation can be added deliberately rather than assumed by template wording.

### Contract Implementation Note

- The JSON schema is repository-tooling oriented and describes the guardrail pack the workflow must express during planning, even if the first implementation lives primarily in markdown templates and checklists.
- The OpenAPI file is logical rather than transport-prescriptive. It documents workflow semantics for authoring, review, signal assessment, and exception handling, not a runtime service.
- The design intentionally avoids new runtime services, CLI tooling, or CI bots. The contract artifacts are structured planning aids inside this feature set, not a new maintained subsystem.

### Deployment Sequencing Note

- No database migration is planned.
- No asset publish step changes.
- Recommended rollout order: finalize the feature-local guardrail pack first, then update the SpecKit templates, then update `.specify/README.md`, then add any minimal secondary cross-reference if needed, then run the representative validation walkthroughs, and finally record which automation candidates remain intentionally deferred.