ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

spec: finalize enforcement review guardrails workflow #250

Merged
ahmido merged 2 commits from 201-enforcement-review-guardrails into dev 2026-04-18 22:46:08 +00:00
Conversation 0 Commits 2 Files Changed 16 +2244 -30
16 changed files with 2244 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
.github/agents/copilot-instructions.md vendored
View File

@ -208,6 +208,8 @@ ## Active Technologies
- Markdown governance artifacts in a PHP 8.4.15 / Laravel 12 / Filament v5 / Livewire v4 repository + `.specify/memory/constitution.md`, `docs/ui/operator-ux-surface-standards.md`, adjacent Specs 196 through 199, existing UI rule IDs `UI-SURF-001`, `ACTSURF-001`, `UI-HARD-001`, `UI-EX-001`, `UI-FIL-001`, `DECIDE-001`, and `UX-001` (200-filament-surface-rules)
- Astro 6.0.0 templates + TypeScript 5.x (explicit setup in `apps/website`) + Astro 6, Tailwind CSS v4, custom Astro component primitives (shadcn-inspired), lightweight Playwright browser smoke tests (213-website-foundation-v0)
- Static filesystem content, styles, and assets under `apps/website/src` and `apps/website/public`; no database (213-website-foundation-v0)
- 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 + `.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 (201-enforcement-review-guardrails)
- Repository-owned markdown and contract artifacts under `.specify/` and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/201-enforcement-review-guardrails/`; no product database persistence (201-enforcement-review-guardrails)
- PHP 8.4.15 (feat/005-bulk-operations)
@ -242,9 +244,8 @@ ## Code Style
PHP 8.4.15: Follow standard conventions
## Recent Changes
- 201-enforcement-review-guardrails: Added 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 + `.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
- 213-website-foundation-v0: Added Astro 6.0.0 templates + TypeScript 5.x (explicit setup in `apps/website`) + Astro 6, Tailwind CSS v4, custom Astro component primitives (shadcn-inspired), lightweight Playwright browser smoke tests
- 200-filament-surface-rules: Added Markdown governance artifacts in a PHP 8.4.15 / Laravel 12 / Filament v5 / Livewire v4 repository + `.specify/memory/constitution.md`, `docs/ui/operator-ux-surface-standards.md`, adjacent Specs 196 through 199, existing UI rule IDs `UI-SURF-001`, `ACTSURF-001`, `UI-HARD-001`, `UI-EX-001`, `UI-FIL-001`, `DECIDE-001`, and `UX-001`
- 199-global-context-shell-contract: Added PHP 8.4.15 + Laravel 12, Filament v5, Livewire v4, Pest v4, Tailwind CSS v4, existing `WorkspaceContext`, `OperateHubShell`, `EnsureFilamentTenantSelected`, `WorkspaceRedirectResolver`, `WorkspaceIntendedUrl`, `TenantPageCategory`, and `ResolvesPanelTenantContext`
- 212-test-authoring-guardrails: Added Markdown for repository governance artifacts, JSON Schema plus logical OpenAPI for planning contracts, and Bash-backed SpecKit scripts already present in the repo + `.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`, `README.md`, and the existing Specs 206 through 211 governance vocabulary
<!-- MANUAL ADDITIONS START -->
<!-- MANUAL ADDITIONS END -->

31
.specify/README.md
View File

@ -11,25 +11,46 @@ ## Important
- `tasks.md`
- `checklists/requirements.md`
- Runtime-changing or test-affecting work MUST carry actual test-purpose classification (`Unit`, `Feature`, `Heavy-Governance`, `Browser`), affected lanes, fixture/default cost risks, heavy-family changes, escalation decisions, and minimal validation commands through the active `spec.md`, `plan.md`, and `tasks.md`.
- Review-oriented checklists MUST surface lane fit, hidden defaults, heavy-family visibility, and runtime-budget follow-up before merge; lane upkeep belongs to the feature, not to a later cleanup pass.
- Review-oriented checklists MUST surface nativity, shared-family boundaries, state-layer ownership, exception spread, proof depth, and close-out targeting before merge.
- `.specify/` is the operational workflow. `docs/ui/operator-ux-surface-standards.md` remains a rule/reference document, not a second checklist or review process.
## Author Entry Point
Use the active feature's `spec.md`, `plan.md`, and `tasks.md` in that order.
1. Fill the spec's UI / Surface Guardrail Impact section once. If there is no operator-facing surface change, write a concise `N/A` and do not invent extra prose downstream.
2. Turn that classification into plan-level handling modes, repository-signal treatment, required proof depth, and the named active feature PR close-out entry.
3. Carry the same terms into tasks so implementation, review, definition-of-done, exception documentation, and smoke coverage all point at the same guardrail decision.
## Review Entry Point
Use the active feature's `spec.md`, `plan.md`, and `tasks.md` together with the generated checklist based on `.specify/templates/checklist-template.md`.
1. Confirm the spec names the affected validation lane(s) or a deliberate `N/A`, the test family impact, setup-cost impact, reviewer handoff, and any escalation outcome.
2. Confirm the plan turns that into changed test types, narrowest proving commands, helper/default widening checks, and the note target for budget or trend drift.
3. Apply the checklist and end with one explicit outcome: `keep`, `split`, `document-in-feature`, `follow-up-spec`, or `reject-or-split`.
1. Confirm the spec names the guardrail impact once: native/custom classification, shared-family relevance, state-layer ownership, exception need, and any low-impact `N/A` path.
2. Confirm the plan turns that into handling modes, repository-signal treatment, required test or smoke depth, and the named active feature PR close-out entry.
3. Apply the checklist and end with both one review outcome class (`blocker`, `strong-warning`, `documentation-required-exception`, or `acceptable-special-case`) and one workflow outcome (`keep`, `split`, `document-in-feature`, `follow-up-spec`, or `reject-or-split`).
4. If a guarded surface or exception remains in scope, ensure the active feature PR close-out entry records the final note rather than leaving the decision in scattered review comments.
## Low-Impact Rule
- Docs-only or template-only work may answer `N/A` or `none`.
- Do not force fake lane prose when no runtime or suite impact exists.
- Do not force fake surface, lane, or exception prose when no operator-facing change or runtime impact exists.
- Use the low-impact path to stay fast, not to hide a real guarded surface change.
## Escalation Rule
- Use `blocker` when fake-native drift, hidden host drift, unresolved state ownership, or missing exception boundaries remain.
- Use `strong-warning` when the change can proceed only after the active workflow records the guardrail risk explicitly.
- Use `documentation-required-exception` when default rules are intentionally relaxed and the bounded exception record is the remaining requirement.
- Use `acceptable-special-case` only when the change already fits the declared guardrail contract.
- Use `document-in-feature` for contained cost or drift that belongs in the active feature.
- Use `follow-up-spec` only for recurring pain or structural lane or family changes.
- Use `reject-or-split` when hidden test cost or wrong-lane scope is still unresolved.
## Close-Out Rule
- The named close-out target for guarded work is the active feature PR close-out entry `Guardrail / Exception / Smoke Coverage`.
- That entry records the low-impact or representative scenario used, the outcome class, handling mode, workflow outcome, required tests or manual smoke, any exception boundary, duplicate-prompt notes, and any deferred automation.
- If the change is genuinely low-impact, record a concise `N/A` note rather than fabricating guardrail spread.
The files `.specify/spec.md`, `.specify/plan.md`, `.specify/tasks.md` may exist as legacy references only.

56
.specify/templates/checklist-template.md
View File

@ -5,39 +5,53 @@ # [CHECKLIST TYPE] Checklist: [FEATURE NAME]
**Feature**: [Link to spec.md or relevant documentation]
**Note**: This checklist is generated by the `/speckit.checklist` command based on feature context and requirements.
If the checklist covers runtime behavior or test-surface changes, use it to reach one explicit outcome: `keep`, `split`, `document-in-feature`, `follow-up-spec`, or `reject-or-split`.
Low-impact docs-only or template-only work may mark runtime-only checks `N/A`, but should still leave one explicit outcome.
If the checklist covers UI or surface work, use it to reach both one review
outcome class (`blocker`, `strong-warning`,
`documentation-required-exception`, or `acceptable-special-case`) and one
workflow outcome (`keep`, `split`, `document-in-feature`,
`follow-up-spec`, or `reject-or-split`). Low-impact docs-only or
template-only work may mark runtime-only checks `N/A`, but should still
leave one explicit workflow outcome and one note explaining why no
guardrail spread exists.
## Lane Fit
## Applicability And Low-Impact Gate
- [ ] CHK001 The chosen validation lane is the narrowest lane or lane mix that proves the change.
- [ ] CHK002 The test stays in the smallest honest family (`Unit`, `Feature`, `Heavy-Governance`, `Browser`) and does not hide broader purpose behind a narrow label.
- [ ] CHK001 The change explicitly says whether an operator-facing surface or guardrail workflow surface is affected; low-impact `N/A` handling is used once and not contradicted elsewhere.
- [ ] CHK002 The spec, plan, and task artifacts carry forward the same native/custom classification, shared-family relevance, state-layer ownership, and exception need without inventing second wording.
## Breadth And Cost
## Native, Shared-Family, And State Ownership
- [ ] CHK003 The changed or added test is no broader than the behavior it proves.
- [ ] CHK004 Any database, Livewire, Filament, or browser surface is justified over a narrower alternative.
- [ ] CHK005 Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is explicit and locally justified.
- [ ] CHK003 The surface remains native/shared-primitives first; fake-native controls, GET-form page-body interactions, and simple-overview replacements are not treated as harmless customization.
- [ ] CHK004 Any shared-detail or shared-family surface keeps one shared contract, and any host variation is either folded back into that contract or explicitly bounded as an exception.
- [ ] CHK005 Shell, page, detail, and URL/query state owners are named once and do not collapse into one another.
- [ ] CHK006 The likely next operator action and the primary inspect/open model stay coherent with the declared surface class.
## Validation And Drift
## Signals, Exceptions, And Test Depth
- [ ] CHK006 The minimal reviewer validation command is written explicitly and matches the declared lane.
- [ ] CHK007 Any material budget, baseline, trend, or runtime-drift note is recorded in the active spec or PR.
- [ ] CHK007 Any triggered repository signal is classified with one handling mode: `hard-stop-candidate`, `review-mandatory`, `exception-required`, or `report-only`.
- [ ] CHK008 Any deviation from default rules includes a bounded exception record naming the broken rule, product reason, standardized parts, spread-control rule, and the active feature PR close-out entry.
- [ ] CHK009 The required surface test profile is explicit: `shared-detail-family`, `monitoring-state-page`, `global-context-shell`, `exception-coded-surface`, or `standard-native-filament`.
- [ ] CHK010 The chosen test family/lane and any manual smoke are the narrowest honest proof for the declared surface class, and `standard-native-filament` relief is used when no special contract exists.
## Escalation Outcome
## Review Outcome
- [ ] CHK008 One explicit outcome is chosen: `keep`, `split`, `document-in-feature`, `follow-up-spec`, or `reject-or-split`.
- [ ] CHK009 New heavy families, new browser coverage, revived expensive defaults, or material lane-cost shifts are not left implicit.
- [ ] CHK011 One review outcome class is chosen: `blocker`, `strong-warning`, `documentation-required-exception`, or `acceptable-special-case`.
- [ ] CHK012 One workflow outcome is chosen: `keep`, `split`, `document-in-feature`, `follow-up-spec`, or `reject-or-split`.
- [ ] CHK013 The final note location is explicit: the active feature PR close-out entry for guarded work, or a concise `N/A` note for low-impact changes.
## Notes
- `keep`: current lane, family, and setup are justified.
- `split`: scope is valid, but the test or helper spread should be narrowed before merge.
- `document-in-feature`: the change is acceptable, but the cost or drift must be recorded in the active spec or PR.
- `follow-up-spec`: recurring pain or structural lane or family changes need dedicated governance work.
- `reject-or-split`: hidden cost, wrong lane, or unjustified breadth blocks merge as proposed.
- `blocker`: the change conflicts with the declared surface contract or guardrail and cannot proceed as proposed.
- `strong-warning`: the change may proceed only after the active workflow records the remaining guardrail risk explicitly.
- `documentation-required-exception`: the change is valid only once a bounded exception and close-out note exist.
- `acceptable-special-case`: the change is legitimate without extra escalation beyond ordinary documentation.
- `keep`: the current scope, guardrail handling, and proof depth are justified.
- `split`: the intent is valid, but the scope should narrow before merge.
- `document-in-feature`: the change is acceptable, but the active feature must record the exception, signal handling, or proof notes explicitly.
- `follow-up-spec`: the issue is recurring or structural and needs dedicated governance follow-up.
- `reject-or-split`: hidden drift, unresolved exception spread, or wrong proof depth blocks merge as proposed.
- Check items off as completed: `[x]`
- Add comments or findings inline
- Link to relevant resources or documentation
- Items are numbered sequentially for easy reference
- Reviewer-facing runtime checklists SHOULD stop merge when lane fit, hidden cost, heavy-family drift, or escalation handling is unclear.
- Reviewer-facing checklists SHOULD stop merge when nativity, shared-family boundaries, state ownership, exception spread, test depth, or escalation handling is unclear.

22
.specify/templates/plan-template.md
View File

@ -28,6 +28,21 @@ ## Technical Context
**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]
**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
## UI / Surface Guardrail Plan
> **Fill for operator-facing or guardrail-relevant workflow changes. Docs-only or template-only work may use concise `N/A`. Copy the spec classification forward; do not rename or expand it here.**
- **Guardrail scope**: [no operator-facing surface change / changed surfaces / workflow-only guardrail change]
- **Native vs custom classification summary**: [native / custom / mixed / N/A]
- **Shared-family relevance**: [none / list affected shared families]
- **State layers in scope**: [shell / page / detail / URL-query / none]
- **Handling modes by drift class or surface**: [hard-stop-candidate / review-mandatory / exception-required / report-only / N/A]
- **Repository-signal treatment**: [report-only / review-mandatory / exception-required / future hard-stop candidate / N/A]
- **Special surface test profiles**: [standard-native-filament / shared-detail-family / monitoring-state-page / global-context-shell / exception-coded-surface / N/A]
- **Required tests or manual smoke**: [functional-core / state-contract / exception-fallback / manual-smoke / N/A]
- **Exception path and spread control**: [none / describe the named exception boundary]
- **Active feature PR close-out entry**: [Guardrail / Exception / Smoke Coverage / N/A]
## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
@ -89,6 +104,11 @@ ## Constitution Check
selection actions, navigation, and object actions; risky or rare
actions are grouped and ordered by meaning/frequency/risk; any special
type or workflow-hub exception is explicit and justified
- UI review workflow: native/custom classification, shared-family
relevance, state-layer ownership, repository-signal treatment,
exception path, and the active feature PR close-out entry stay
explicit without duplicating the same decision across spec, plan,
tasks, checklist, and close-out surfaces
## Test Governance Check
@ -101,10 +121,12 @@ ## Test Governance Check
- **Fixture / helper / factory / seed / context cost risks**: [none / describe]
- **Expensive defaults or shared helper growth introduced?**: [no / describe explicit opt-in path]
- **Heavy-family additions, promotions, or visibility changes**: [none / describe]
- **Surface-class relief / special coverage rule**: [standard-native relief / named special profile / N/A]
- **Closing validation and reviewer handoff**: [What must be re-run, what reviewers should verify, and what exact proof command they should rely on]
- **Budget / baseline / trend follow-up**: [none / describe]
- **Review-stop questions**: [lane fit / breadth / hidden cost / heavy-family risk / escalation]
- **Escalation path**: [none / document-in-feature / follow-up-spec / reject-or-split]
- **Active feature PR close-out entry**: [Guardrail / Exception / Smoke Coverage / N/A]
- **Why no dedicated follow-up spec is needed**: [Routine upkeep stays inside this feature unless recurring pain or structural lane changes justify a separate spec]
## Project Structure

20
.specify/templates/spec-template.md
View File

@ -35,11 +35,23 @@ ## Spec Scope Fields *(mandatory)*
- **Default filter behavior when tenant-context is active**: [e.g., prefilter to current tenant]
- **Explicit entitlement checks preventing cross-tenant leakage**: [Describe checks]
## UI / Surface Guardrail Impact *(mandatory when operator-facing surfaces are changed; otherwise write `N/A`)*
Use this section to classify UI and surface risk once. If the feature does
not change an operator-facing surface, write `N/A - no operator-facing surface
change` here and do not invent duplicate prose in the downstream surface tables.
| Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / `N/A` Note |
|---|---|---|---|---|---|---|
| e.g. Tenant policies page | yes | Native Filament + shared primitives | none | page, detail | no | n/a |
| e.g. Docs-only change | no | N/A | none | none | no | `N/A - repository workflow only` |
## Decision-First Surface Role *(mandatory when operator-facing surfaces are changed)*
If this feature adds or materially changes an operator-facing surface,
fill out one row per affected surface. This role is orthogonal to the
Action Surface Class / Surface Type below.
Action Surface Class / Surface Type below. Reuse the exact surface names
and classifications from the UI / Surface Guardrail Impact section above.
| Surface | Decision Role | Human-in-the-loop Moment | Immediately Visible for First Decision | On-Demand Detail / Evidence | Why This Is Primary or Why Not | Workflow Alignment | Attention-load Reduction |
|---|---|---|---|---|---|---|---|
@ -50,7 +62,8 @@ ## UI/UX Surface Classification *(mandatory when operator-facing surfaces are ch
If this feature adds or materially changes an operator-facing list, detail, queue, audit, config, or report surface,
fill out one row per affected surface. Declare the broad Action Surface
Class first, then the detailed Surface Type. Keep this table in sync
with the Decision-First Surface Role section above.
with the Decision-First Surface Role section above and avoid renaming the
same surface a second time.
| Surface | Action Surface Class | Surface Type | Likely Next Operator Action | Primary Inspect/Open Model | Row Click | Secondary Actions Placement | Destructive Actions Placement | Canonical Collection Route | Canonical Detail Route | Scope Signals | Canonical Noun | Critical Truth Visible by Default | Exception Type / Justification |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
@ -98,9 +111,12 @@ ## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)*
- **New or expanded test families**: [none / describe]
- **Fixture / helper cost impact**: [none / describe new defaults, factories, seeds, helpers, browser setup, provider setup, workspace or membership context, session state, etc.]
- **Heavy-family visibility / justification**: [none / explain any heavy-governance or browser addition and how it remains explicit in naming, lane choice, and review]
- **Special surface test profile**: [standard-native-filament / shared-detail-family / monitoring-state-page / global-context-shell / exception-coded-surface / N/A]
- **Standard-native relief or required special coverage**: [ordinary feature coverage only / describe required tests or smoke checks]
- **Reviewer handoff**: [What reviewers must confirm about lane fit, hidden cost, heavy-family visibility, and the exact proof command]
- **Budget / baseline / trend impact**: [none / expected drift + follow-up]
- **Escalation needed**: [none / document-in-feature / follow-up-spec / reject-or-split]
- **Active feature PR close-out entry**: [Guardrail / Exception / Smoke Coverage / N/A]
- **Planned validation commands**: [Exact minimal commands reviewers should run]
## User Scenarios & Testing *(mandatory)*

9
.specify/templates/tasks-template.md
View File

@ -46,6 +46,13 @@ # Tasks: [FEATURE NAME]
- using source/domain terms only where same-screen disambiguation is required,
- aligning button labels, modal titles, run titles, notifications, and audit prose to the same domain vocabulary,
- removing implementation-first wording from primary operator-facing copy.
**UI / Surface Guardrails**: If this feature adds or changes operator-facing surfaces or the workflow that governs them, tasks MUST include:
- carrying forward the spec's native/custom classification, shared-family relevance, state-layer ownership, and exception need into implementation work without renaming the same decision,
- classifying any triggered repository signals with one handling mode (`hard-stop-candidate`, `review-mandatory`, `exception-required`, or `report-only`),
- adding explicit review or definition-of-done work when a guarded surface class, repository signal, or exception path is involved,
- adding required tests or manual smoke for `shared-detail-family`, `monitoring-state-page`, `global-context-shell`, or `exception-coded-surface`, OR recording `standard-native-filament` relief when no special contract exists,
- adding exception documentation and spread-control tasks whenever default surface rules are intentionally relaxed,
- recording the active feature PR close-out entry with guardrail class, exception status, required tests/manual smoke, low-impact `N/A` use, and any deferred automation.
**Operator Surfaces**: If this feature adds or materially refactors an operator-facing page or flow, tasks MUST include:
- classifying each affected surface as Primary Decision, Secondary
Context, or Tertiary Evidence / Diagnostics and keeping that role in
@ -141,6 +148,7 @@ ## Test Governance Checklist
- [ ] New or changed tests stay in the smallest honest family, and any heavy-governance or browser addition is explicit.
- [ ] Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is isolated or documented.
- [ ] Planned validation commands cover the change without pulling in unrelated lane cost.
- [ ] The declared surface test profile or `standard-native-filament` relief is explicit.
- [ ] Any material budget, baseline, trend, or escalation note is recorded in the active spec or PR.
## Format: `[ID] [P?] [Story] Description`
@ -287,6 +295,7 @@ ## Phase N: Polish & Cross-Cutting Concerns
- [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/
- [ ] TXXX Security hardening
- [ ] TXXX Proportionality cleanup: remove or collapse superseded layers introduced during implementation
- [ ] TXXX Record the active feature PR close-out entry with guardrail class, exception status, proof depth, and deferred automation
- [ ] TXXX Run quickstart.md validation
---

5
docs/ui/operator-ux-surface-standards.md
View File

@ -489,6 +489,11 @@ ## 14. Adoption Rules
- new specs that materially affect operator UX
Specs should explicitly reference this document where relevant.
Operational authoring and review workflow lives in `.specify/templates/spec-template.md`,
`.specify/templates/plan-template.md`, `.specify/templates/tasks-template.md`,
`.specify/templates/checklist-template.md`, and `.specify/README.md`.
This document remains the rule and reference layer, not a second checklist
or close-out workflow.
Recommended spec fields:

37
specs/201-enforcement-review-guardrails/checklists/requirements.md Normal file
View File

@ -0,0 +1,37 @@
# Specification Quality Checklist: Enforcement & Review Guardrails
**Purpose**: Validate specification completeness and quality before proceeding to planning
**Created**: 2026-04-18
**Feature**: [spec.md](../spec.md)
## Content Quality
- [x] No implementation details (languages, frameworks, APIs)
- [x] Focused on user value and business needs
- [x] Written for non-technical stakeholders
- [x] All mandatory sections completed
## Requirement Completeness
- [x] No [NEEDS CLARIFICATION] markers remain
- [x] Requirements are testable and unambiguous
- [x] Success criteria are measurable
- [x] Success criteria are technology-agnostic (no implementation details)
- [x] All acceptance scenarios are defined
- [x] Edge cases are identified
- [x] Scope is clearly bounded
- [x] Dependencies and assumptions identified
## Feature Readiness
- [x] All functional requirements have clear acceptance criteria
- [x] User scenarios cover primary flows
- [x] Feature meets measurable outcomes defined in Success Criteria
- [x] No implementation details leak into specification
## Notes
- Validated against the drafted Spec 201 on 2026-04-18 after converting the source outline into the repository template and measurable requirement language.
- Optional operator-surface classification tables are intentionally omitted because this feature governs workflow and review mechanics rather than changing a concrete runtime surface.
- Filament and repository-signal terminology is intentional product vocabulary for this governance slice, not code-level implementation guidance.
- No clarification markers remain. The spec is ready for `/speckit.plan`.

450
specs/201-enforcement-review-guardrails/contracts/guardrail-governance.logical.openapi.yaml Normal file
View File

@ -0,0 +1,450 @@
openapi: 3.1.0
info:
title: UI Surface Enforcement & Review Guardrails
version: 1.0.0
description: |
Logical contract for the repository-owned guardrail workflow introduced by Spec 201.
It documents authoring, review, repository-signal, test-guardrail, and exception
semantics. It is not a public HTTP API.
servers:
- url: https://tenantpilot.local/logical
paths:
/logical/ui-guardrails/spec-impact/validate:
post:
summary: Validate one spec-level UI guardrail impact block
operationId: validateSpecGuardrailImpact
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SpecImpactValidationRequest'
responses:
'200':
description: Spec guardrail impact evaluated
content:
application/json:
schema:
$ref: '#/components/schemas/SpecImpactValidationResult'
/logical/ui-guardrails/reviews/classify:
post:
summary: Classify one UI or surface change through the reviewer checklist
operationId: classifyReviewOutcome
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ReviewClassificationRequest'
responses:
'200':
description: Review classification returned
content:
application/json:
schema:
$ref: '#/components/schemas/ReviewClassificationResult'
/logical/ui-guardrails/repository-signals/assess:
post:
summary: Assess repository-level technical signals for a change
operationId: assessRepositorySignals
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RepositorySignalAssessmentRequest'
responses:
'200':
description: Repository-signal assessment returned
content:
application/json:
schema:
$ref: '#/components/schemas/RepositorySignalAssessmentResult'
/logical/ui-guardrails/test-guardrails/resolve:
post:
summary: Resolve the required test profile for a surface contract class
operationId: resolveTestGuardrailProfile
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TestGuardrailResolutionRequest'
responses:
'200':
description: Test guardrail profile returned
content:
application/json:
schema:
$ref: '#/components/schemas/TestGuardrailResolutionResult'
/logical/ui-guardrails/exceptions/assess:
post:
summary: Assess whether an exception record is complete and bounded
operationId: assessExceptionWorkflow
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionAssessmentRequest'
responses:
'200':
description: Exception assessment returned
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionAssessmentResult'
/logical/ui-guardrails/closeout/prepare:
post:
summary: Prepare the active feature PR close-out entry for guarded work
operationId: prepareCloseoutEntry
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CloseoutPreparationRequest'
responses:
'200':
description: Close-out entry requirements returned
content:
application/json:
schema:
$ref: '#/components/schemas/CloseoutPreparationResult'
/logical/ui-guardrails/guidance:
get:
summary: Read the current guardrail guidance pack
operationId: readGuardrailGuidance
responses:
'200':
description: Guardrail guidance returned
content:
application/json:
schema:
$ref: '#/components/schemas/GuardrailGuidancePack'
components:
schemas:
SpecImpactValidationRequest:
type: object
additionalProperties: false
required:
- specPath
- uiSurfaceChange
- nativeCustomClassification
- stateLayers
- sharedFamilyRelevance
- exceptionNeeded
properties:
specPath:
type: string
uiSurfaceChange:
type: boolean
nativeCustomClassification:
type: string
stateLayers:
type: array
items:
type: string
enum:
- shell
- page
- detail
sharedFamilyRelevance:
type: string
exceptionNeeded:
type: boolean
plannedGuardrailClasses:
type: array
items:
type: string
closeoutEntryTarget:
type: string
SpecImpactValidationResult:
type: object
additionalProperties: false
required:
- status
- findings
- closeoutEntryTarget
properties:
status:
type: string
enum:
- complete
- needs-revision
findings:
type: array
items:
type: string
reviewerHandOff:
type: string
closeoutEntryTarget:
type: string
ReviewClassificationRequest:
type: object
additionalProperties: false
required:
- changeRef
- triggeredMappings
- checklistAnswers
properties:
changeRef:
type: string
triggeredMappings:
type: array
items:
type: string
checklistAnswers:
type: array
items:
type: string
exceptionClaimed:
type: boolean
closeoutEntryTarget:
type: string
ReviewClassificationResult:
type: object
additionalProperties: false
required:
- outcomeClass
- workflowOutcome
- recordLocation
properties:
outcomeClass:
type: string
enum:
- blocker
- strong-warning
- documentation-required-exception
- acceptable-special-case
workflowOutcome:
type: string
enum:
- keep
- split
- document-in-feature
- follow-up-spec
- reject-or-split
missingEvidence:
type: array
items:
type: string
recordLocation:
type: string
RepositorySignalAssessmentRequest:
type: object
additionalProperties: false
required:
- changeRef
- signalIds
properties:
changeRef:
type: string
signalIds:
type: array
items:
type: string
exceptionClaimed:
type: boolean
scopeNote:
type: string
RepositorySignalAssessmentResult:
type: object
additionalProperties: false
required:
- status
- handlingModes
- closeoutEntryRequired
properties:
status:
type: string
enum:
- complete
- needs-review
handlingModes:
type: array
items:
type: string
requiresException:
type: boolean
closeoutEntryRequired:
type: boolean
notes:
type: array
items:
type: string
TestGuardrailResolutionRequest:
type: object
additionalProperties: false
required:
- surfaceClass
properties:
surfaceClass:
type: string
enum:
- shared-detail-family
- monitoring-state-page
- global-context-shell
- exception-coded-surface
- standard-native-filament
changedContractAreas:
type: array
items:
type: string
exceptionType:
type: string
TestGuardrailResolutionResult:
type: object
additionalProperties: false
required:
- requiredTestTypes
- specialCoverageRequired
- profileId
properties:
profileId:
type: string
requiredTestTypes:
type: array
items:
type: string
manualSmokeExpectations:
type: array
items:
type: string
specialCoverageRequired:
type: boolean
ExceptionAssessmentRequest:
type: object
additionalProperties: false
required:
- changeRef
- exceptionType
- brokenRules
- boundaryPlan
- closeoutEntryTarget
properties:
changeRef:
type: string
exceptionType:
type: string
brokenRules:
type: array
items:
type: string
productReason:
type: string
boundaryPlan:
type: array
items:
type: string
standardizationPlan:
type: array
items:
type: string
closeoutEntryTarget:
type: string
ExceptionAssessmentResult:
type: object
additionalProperties: false
required:
- status
- spreadAllowed
- closeoutEntryRequired
properties:
status:
type: string
enum:
- complete
- needs-revision
spreadAllowed:
type: boolean
closeoutEntryRequired:
type: boolean
closeoutNotes:
type: array
items:
type: string
CloseoutPreparationRequest:
type: object
additionalProperties: false
required:
- changeRef
- outcomeClass
- handlingModes
- workflowOutcome
properties:
changeRef:
type: string
outcomeClass:
type: string
enum:
- blocker
- strong-warning
- documentation-required-exception
- acceptable-special-case
handlingModes:
type: array
items:
type: string
workflowOutcome:
type: string
enum:
- keep
- split
- document-in-feature
- follow-up-spec
- reject-or-split
proofDepth:
type: array
items:
type: string
duplicatePromptNotes:
type: array
items:
type: string
CloseoutPreparationResult:
type: object
additionalProperties: false
required:
- entryName
- requiredFields
properties:
entryName:
type: string
requiredFields:
type: array
items:
type: string
lowImpactAllowed:
type: boolean
notes:
type: array
items:
type: string
GuardrailGuidancePack:
type: object
additionalProperties: false
required:
- entryPoints
- outcomeClasses
- workflowOutcomes
- closeoutEntryName
properties:
entryPoints:
type: array
items:
type: string
outcomeClasses:
type: array
items:
type: string
workflowOutcomes:
type: array
items:
type: string
closeoutEntryName:
type: string
notes:
type: array
items:
type: string

451
specs/201-enforcement-review-guardrails/contracts/guardrail-governance.schema.json Normal file
View File

@ -0,0 +1,451 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://tenantpilot.local/specs/201/guardrail-governance.schema.json",
"title": "UI Surface Guardrail Governance Pack",
"description": "Repository-owned contract for the review, repository-signal, test-guardrail, exception, and workflow-touchpoint artifacts introduced by Spec 201.",
"type": "object",
"additionalProperties": false,
"required": [
"schemaVersion",
"ruleMappings",
"reviewChecklist",
"repositorySignals",
"testGuardrails",
"exceptionWorkflow",
"workflowTouchpoints",
"validationScenarios",
"closeoutEntry"
],
"properties": {
"schemaVersion": {
"type": "string"
},
"ruleMappings": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/$defs/ruleMapping"
}
},
"reviewChecklist": {
"$ref": "#/$defs/reviewChecklist"
},
"repositorySignals": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/$defs/repositorySignal"
}
},
"testGuardrails": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/$defs/testGuardrail"
}
},
"exceptionWorkflow": {
"$ref": "#/$defs/exceptionWorkflow"
},
"workflowTouchpoints": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/$defs/workflowTouchpoint"
}
},
"validationScenarios": {
"type": "array",
"minItems": 2,
"items": {
"$ref": "#/$defs/validationScenario"
}
},
"closeoutEntry": {
"$ref": "#/$defs/closeoutEntry"
}
},
"$defs": {
"ruleMapping": {
"type": "object",
"additionalProperties": false,
"required": [
"mappingId",
"sourceRuleId",
"problemClass",
"operationalClasses",
"handlingMode",
"representativeCases",
"targetWorkflowSurfaces"
],
"properties": {
"mappingId": { "type": "string" },
"sourceRuleId": { "type": "string" },
"problemClass": { "type": "string" },
"operationalClasses": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"enum": [
"review",
"repository-signal",
"test-guardrail",
"exception",
"workflow-touchpoint"
]
}
},
"handlingMode": {
"type": "string",
"enum": [
"hard-stop-candidate",
"review-mandatory",
"exception-required",
"report-only"
]
},
"representativeCases": {
"type": "array",
"items": { "type": "string" }
},
"targetWorkflowSurfaces": {
"type": "array",
"minItems": 1,
"items": { "type": "string" }
},
"deferredAutomation": {
"type": "array",
"items": { "type": "string" }
}
}
},
"reviewChecklist": {
"type": "object",
"additionalProperties": false,
"required": [
"checklistId",
"questions",
"outcomeClasses",
"workflowOutcomes",
"maxReviewMinutes"
],
"properties": {
"checklistId": { "type": "string" },
"questions": {
"type": "array",
"minItems": 1,
"items": { "$ref": "#/$defs/reviewQuestion" }
},
"outcomeClasses": {
"type": "array",
"items": {
"type": "string",
"enum": [
"blocker",
"strong-warning",
"documentation-required-exception",
"acceptable-special-case"
]
}
},
"workflowOutcomes": {
"type": "array",
"items": {
"type": "string",
"enum": [
"keep",
"split",
"document-in-feature",
"follow-up-spec",
"reject-or-split"
]
}
},
"maxReviewMinutes": {
"type": "integer",
"minimum": 1
}
}
},
"reviewQuestion": {
"type": "object",
"additionalProperties": false,
"required": [
"questionId",
"category",
"prompt",
"appliesWhen",
"linkedMappings",
"evidenceExpected",
"defaultOutcomeClass"
],
"properties": {
"questionId": { "type": "string" },
"category": {
"type": "string",
"enum": [
"surface-classification",
"native-usage",
"shared-family",
"state-layer",
"exception",
"test-coverage"
]
},
"prompt": { "type": "string" },
"appliesWhen": { "type": "string" },
"linkedMappings": {
"type": "array",
"minItems": 1,
"items": { "type": "string" }
},
"evidenceExpected": { "type": "string" },
"defaultOutcomeClass": {
"type": "string",
"enum": [
"blocker",
"strong-warning",
"documentation-required-exception",
"acceptable-special-case"
]
}
}
},
"repositorySignal": {
"type": "object",
"additionalProperties": false,
"required": [
"signalId",
"label",
"patternType",
"confidenceLevel",
"handlingMode",
"exceptionPath",
"futurePromotion"
],
"properties": {
"signalId": { "type": "string" },
"label": { "type": "string" },
"patternType": {
"type": "string",
"enum": ["grep", "search", "path-pattern", "manual"]
},
"searchScopePaths": {
"type": "array",
"items": { "type": "string" }
},
"triggerExamples": {
"type": "array",
"items": { "type": "string" }
},
"confidenceLevel": {
"type": "string",
"enum": ["high", "medium", "low"]
},
"handlingMode": {
"type": "string",
"enum": [
"report-only",
"review-mandatory",
"exception-required",
"hard-stop-candidate"
]
},
"exceptionPath": { "type": "string" },
"futurePromotion": { "type": "string" }
}
},
"testGuardrail": {
"type": "object",
"additionalProperties": false,
"required": [
"profileId",
"surfaceClass",
"triggers",
"requiredTestTypes",
"manualSmokeExpectations",
"standardCoverageRule",
"exceptionHandlingRule"
],
"properties": {
"profileId": { "type": "string" },
"surfaceClass": {
"type": "string",
"enum": [
"shared-detail-family",
"monitoring-state-page",
"global-context-shell",
"exception-coded-surface",
"standard-native-filament"
]
},
"triggers": {
"type": "array",
"items": { "type": "string" }
},
"requiredTestTypes": {
"type": "array",
"items": {
"type": "string",
"enum": [
"functional-core",
"state-contract",
"exception-fallback",
"manual-smoke"
]
}
},
"manualSmokeExpectations": {
"type": "array",
"items": { "type": "string" }
},
"standardCoverageRule": { "type": "string" },
"exceptionHandlingRule": { "type": "string" }
}
},
"exceptionWorkflow": {
"type": "object",
"additionalProperties": false,
"required": [
"workflowId",
"supportedExceptionTypes",
"requiredFields",
"boundaryChecks",
"standardizationFields",
"spreadReviewRule",
"closeoutRequirement",
"closeoutNoteTarget"
],
"properties": {
"workflowId": { "type": "string" },
"supportedExceptionTypes": {
"type": "array",
"items": { "type": "string" }
},
"requiredFields": {
"type": "array",
"items": { "type": "string" }
},
"boundaryChecks": {
"type": "array",
"items": { "type": "string" }
},
"standardizationFields": {
"type": "array",
"items": { "type": "string" }
},
"spreadReviewRule": { "type": "string" },
"closeoutRequirement": { "type": "string" },
"closeoutNoteTarget": { "type": "string" }
}
},
"workflowTouchpoint": {
"type": "object",
"additionalProperties": false,
"required": [
"touchpointId",
"artifactPath",
"phase",
"requiredPrompts",
"linkedMappings",
"outcomeTarget"
],
"properties": {
"touchpointId": { "type": "string" },
"artifactPath": { "type": "string" },
"phase": {
"type": "string",
"enum": ["spec", "plan", "tasks", "review", "closeout", "follow-up"]
},
"requiredPrompts": {
"type": "array",
"items": { "type": "string" }
},
"linkedMappings": {
"type": "array",
"items": { "type": "string" }
},
"outcomeTarget": { "type": "string" }
}
},
"validationScenario": {
"type": "object",
"additionalProperties": false,
"required": [
"scenarioId",
"scenarioType",
"representativeArtifact",
"expectedMappings",
"expectedOutcomeClass",
"expectedWorkflowOutcome",
"status",
"notes"
],
"properties": {
"scenarioId": { "type": "string" },
"scenarioType": {
"type": "string",
"enum": [
"low-impact",
"fake-native",
"shared-family",
"state-layer",
"legitimate-exception"
]
},
"representativeArtifact": { "type": "string" },
"expectedMappings": {
"type": "array",
"items": { "type": "string" }
},
"expectedOutcomeClass": {
"type": "string",
"enum": [
"blocker",
"strong-warning",
"documentation-required-exception",
"acceptable-special-case"
]
},
"expectedWorkflowOutcome": {
"type": "string",
"enum": [
"keep",
"split",
"document-in-feature",
"follow-up-spec",
"reject-or-split"
]
},
"status": {
"type": "string",
"enum": ["planned", "validated", "needs-tuning"]
},
"notes": { "type": "string" }
}
},
"closeoutEntry": {
"type": "object",
"additionalProperties": false,
"required": [
"entryName",
"requiredFields",
"noteOwner",
"lowImpactRule",
"deferredAutomationField"
],
"properties": {
"entryName": { "type": "string" },
"requiredFields": {
"type": "array",
"minItems": 1,
"items": { "type": "string" }
},
"noteOwner": { "type": "string" },
"lowImpactRule": { "type": "string" },
"deferredAutomationField": { "type": "string" }
}
}
}
}

298
specs/201-enforcement-review-guardrails/data-model.md Normal file
View File

@ -0,0 +1,298 @@
# Data Model: Enforcement & Review Guardrails
This feature adds repository-owned governance artifacts only. It does not add application database tables, runtime-owned entities, or executable service contracts. All objects below are implemented as markdown guidance, template prompts, checklists, and logical contracts.
Handling modes and review outcome classes are separate concepts in this model. Handling modes describe how a signal or rule is processed in the workflow, while review outcome classes describe the decision reached for a specific change.
## 1. GuardrailRuleMapping
**Purpose**: Maps one Spec 200 or constitution rule family to its operational behavior in review, repository signals, testing, exceptions, and workflow surfaces.
| Field | Type | Description |
|-------|------|-------------|
| `mappingId` | string | Stable identifier for the mapping. |
| `sourceRuleId` | string | Spec 200 or constitution rule family being operationalized. |
| `problemClass` | string | Drift class addressed by the mapping. |
| `operationalClasses` | array | One or more of `review`, `repository-signal`, `test-guardrail`, `exception`, `workflow-touchpoint`. |
| `handlingMode` | string | One of `hard-stop-candidate`, `review-mandatory`, `exception-required`, or `report-only`. |
| `representativeCases` | array | Real repo cases that prove the rule. |
| `targetWorkflowSurfaces` | array | Templates, checklist surfaces, or docs that must express the mapping. |
| `deferredAutomation` | array | Automation or CI work explicitly deferred from the first pass. |
**Validation Rules**
- Every mapping must point to an existing Spec 200 or constitution rule family.
- Every mapping must declare at least one operational class and exactly one first-pass handling mode.
- `hard-stop-candidate` mappings must either have a named exception path or explicitly state `none`.
## 2. ReviewChecklistQuestion
**Purpose**: Represents one mandatory reviewer question used to classify UI and surface work.
| Field | Type | Description |
|-------|------|-------------|
| `questionId` | string | Stable identifier for the review question. |
| `category` | string | `surface-classification`, `native-usage`, `shared-family`, `state-layer`, `exception`, or `test-coverage`. |
| `prompt` | string | The exact decision-grade question. |
| `appliesWhen` | string | Scope rule for when the question must be asked. |
| `linkedMappings` | array | Related `GuardrailRuleMapping` IDs. |
| `evidenceExpected` | string | What the author or reviewer must point to. |
| `defaultOutcomeClass` | string | One of `blocker`, `strong-warning`, `documentation-required-exception`, or `acceptable-special-case`. |
**Validation Rules**
- Questions must be phrased as classification or review-stop decisions, not vague advice.
- Every question must link to at least one guardrail mapping.
- The question set must stay short enough for a representative review pass to complete in under 3 minutes.
## 3. RepositorySignalProfile
**Purpose**: Describes one technically observable red flag that can be reported or escalated during review.
| Field | Type | Description |
|-------|------|-------------|
| `signalId` | string | Stable identifier for the signal. |
| `label` | string | Human-readable signal name. |
| `patternType` | string | `grep`, `search`, `path-pattern`, or `manual`. |
| `searchScopePaths` | array | Paths where the signal applies. |
| `triggerExamples` | array | Observable examples of the pattern. |
| `confidenceLevel` | string | `high`, `medium`, or `low`. |
| `handlingMode` | string | One of `report-only`, `review-mandatory`, `exception-required`, or `hard-stop-candidate`. |
| `exceptionPath` | string | Named exception path or `none`. |
| `futurePromotion` | string | Whether later hardening is allowed and under what condition. |
**Validation Rules**
- Every signal must have a documented handling mode and an exception or review path.
- First-pass automation may not exceed `report-only` unless the signal has high confidence and low ambiguity.
- Signals must stay anchored to real drift cases, not hypothetical future problems.
## 4. TestGuardrailProfile
**Purpose**: Defines the required test and smoke depth for a surface contract class.
| Field | Type | Description |
|-------|------|-------------|
| `profileId` | string | Stable identifier for the surface test profile. |
| `surfaceClass` | string | `shared-detail-family`, `monitoring-state-page`, `global-context-shell`, `exception-coded-surface`, or `standard-native-filament`. |
| `triggers` | array | Conditions that activate the profile. |
| `requiredTestTypes` | array | Required evidence such as `functional-core`, `state-contract`, `exception-fallback`, or `manual-smoke`. |
| `manualSmokeExpectations` | array | Manual review or smoke expectations tied to the profile. |
| `standardCoverageRule` | string | When ordinary feature coverage is enough. |
| `exceptionHandlingRule` | string | How exceptions affect the profile. |
**Validation Rules**
- Every non-standard surface class must declare whether special coverage is mandatory.
- `standard-native-filament` must explicitly state when no additional special guardrail tests are required.
- Profiles must classify by interaction and contract risk, not just by framework or file type.
## 5. ExceptionWorkflowTemplate
**Purpose**: Captures the required fields and checks for a legitimate guardrail exception.
| Field | Type | Description |
|-------|------|-------------|
| `templateId` | string | Stable identifier for the exception template. |
| `exceptionType` | string | Canonical exception type from Spec 200. |
| `brokenRuleIds` | array | Which rule families are being relaxed or not fully satisfied. |
| `requiredFields` | array | Required justification fields the spec or PR must fill. |
| `boundaryChecks` | array | What keeps the exception bounded. |
| `standardizationFields` | array | What remains standardized despite the exception. |
| `spreadReviewRule` | string | What must happen before the exception can extend to new hosts or surfaces. |
| `closeoutNoteTarget` | string | Where the exception must be recorded at completion: the active feature PR close-out entry. |
**Validation Rules**
- Every exception must name the affected rule family and the product reason.
- Boundary checks must be explicit enough to stop silent extension.
- Exception approval is incomplete until the close-out note target is known.
## 6. WorkflowTouchpoint
**Purpose**: Defines one workflow artifact where guardrail behavior must appear.
| Field | Type | Description |
|-------|------|-------------|
| `touchpointId` | string | Stable identifier for the workflow touchpoint. |
| `artifactPath` | string | File path for the workflow surface. |
| `phase` | string | `spec`, `plan`, `tasks`, `review`, `closeout`, or `follow-up`. |
| `requiredPrompts` | array | Questions or fields the artifact must surface. |
| `linkedMappings` | array | Related guardrail mappings. |
| `outcomeTarget` | string | Where the touchpoint records its decision or handoff, including the active feature PR close-out entry when the phase is `closeout`. |
**Validation Rules**
- Every relevant phase from spec to closeout must have at least one touchpoint.
- The active feature PR close-out entry is the single canonical close-out note target for guarded changes.
- The same classification question should not be duplicated unnecessarily across multiple surfaces.
- Touchpoints must point back to existing entry surfaces before any new file is introduced.
## 7. GuardrailAssessment
**Purpose**: Represents the result of classifying one UI or surface change through the workflow.
| Field | Type | Description |
|-------|------|-------------|
| `assessmentId` | string | Stable identifier for one guardrail review. |
| `triggeredMappings` | array | Activated rule mappings. |
| `triggeredSignals` | array | Triggered repository signals, if any. |
| `outcomeClass` | string | `blocker`, `strong-warning`, `documentation-required-exception`, or `acceptable-special-case`. |
| `workflowOutcome` | string | `keep`, `split`, `document-in-feature`, `follow-up-spec`, or `reject-or-split`. |
| `missingEvidence` | array | Missing inputs before the review can close. |
| `recordLocation` | string | Spec, plan, checklist, or the active feature PR close-out entry where the result lives. |
**Validation Rules**
- `blocker` cannot resolve to `keep` while missing evidence remains.
- `documentation-required-exception` requires a completed `ExceptionWorkflowTemplate` entry before the workflow can close as `keep` or `document-in-feature`.
- `recordLocation` must resolve to one declared workflow touchpoint outcome or the active feature PR close-out entry.
- `reject-or-split` is valid when hidden exception spread, unresolved state-layer conflict, or fake-native drift remains uncorrected.
## 8. ValidationScenario
**Purpose**: Represents one scenario used to prove the workflow is both lightweight and effective.
| Field | Type | Description |
|-------|------|-------------|
| `scenarioId` | string | Stable scenario identifier. |
| `scenarioType` | string | `low-impact`, `fake-native`, `shared-family`, `state-layer`, or `legitimate-exception`. |
| `representativeArtifact` | string | Spec, template, or documentation artifact used in the validation walkthrough. |
| `expectedMappings` | array | Rule mappings that should fire. |
| `expectedOutcomeClass` | string | Expected guardrail outcome class. |
| `expectedWorkflowOutcome` | string | Expected workflow outcome. |
| `status` | string | `planned`, `validated`, or `needs-tuning`. |
| `notes` | string | What the scenario proves. |
**Validation Rules**
- At least one `low-impact` and one high-risk scenario must be represented.
- The scenario set must cover fake-native, shared-family, state-layer, and legitimate-exception reasoning.
- Low-impact scenarios must prove that `N/A` paths remain fast and legitimate.
## Relationships
- One `GuardrailRuleMapping` may feed many `ReviewChecklistQuestion`, `RepositorySignalProfile`, and `WorkflowTouchpoint` entries.
- A `RepositorySignalProfile` may trigger a `GuardrailAssessment`, but the final outcome still depends on the associated `ReviewChecklistQuestion` and any `ExceptionWorkflowTemplate`.
- One `TestGuardrailProfile` may be referenced by many `GuardrailRuleMapping` entries when multiple rule families converge on the same surface class.
- One `ExceptionWorkflowTemplate` may be required by many `GuardrailAssessment` records, but each assessment must keep its own bounded record location.
- `ValidationScenario` objects prove that the combined model stays usable across both low-friction and high-risk cases.
## State Transitions
### GuardrailAssessment.workflowOutcome
- `keep` -> `document-in-feature`: allowed when a change is valid but the active feature still needs to record exception or signal handling explicitly.
- `document-in-feature` -> `follow-up-spec`: allowed when review shows the issue is structural, recurring, or likely to need harder automation.
- Any state -> `reject-or-split`: allowed when fake-native drift, hidden exception spread, unresolved host drift, or unresolved state-layer collapse remains.
### ValidationScenario.status
- `planned` -> `validated`: allowed when the workflow can classify the scenario with the expected outcome and without extra categories.
- `planned` -> `needs-tuning`: allowed when wording is ambiguous, repetitive, or too heavy for the scenario.
- `needs-tuning` -> `validated`: allowed after the relevant template, checklist, or guidance text is refined.
## Derived Outputs
The conceptual model must support these concrete outputs:
- a guardrail catalog that maps Spec 200 rule families to operational behavior
- a reviewer question set with fixed outcome classes
- a repository signal catalog with handling modes and exception escape paths
- a surface-class test guardrail matrix
- an exception workflow template with spread-control rules
- workflow touchpoint changes in the spec, plan, task, checklist, and close-out surfaces
- validation scenarios that prove both low-impact and high-risk usability
## Canonical Implementation Snapshot
### GuardrailRuleMapping Records
| `mappingId` | `sourceRuleId` | `problemClass` | `operationalClasses` | `handlingMode` | `representativeCases` | `targetWorkflowSurfaces` | `deferredAutomation` |
|---|---|---|---|---|---|---|---|
| `GRM-001` | `UI-FIL-001`, `UI-HARD-001` | `fake-native-core-control` | `review`, `repository-signal`, `workflow-touchpoint` | `hard-stop-candidate` | Spec 196 fake-native cleanups | `spec-template`, `checklist-template`, `tasks-template`, `.specify/README.md` | `CI hard-stop deferred`, `grep remains report-first` |
| `GRM-002` | `UI-REVIEW-001`, `UI-EX-001` | `shared-family-host-drift` | `review`, `test-guardrail`, `exception`, `workflow-touchpoint` | `review-mandatory` | Spec 197 shared detail contract | `spec-template`, `plan-template`, `checklist-template`, `tasks-template` | `family linting deferred` |
| `GRM-003` | `DECIDE-001`, `OPSURF-001`, `UI-REVIEW-001` | `state-layer-ownership-collapse` | `review`, `repository-signal`, `test-guardrail`, `workflow-touchpoint` | `review-mandatory` | Specs 198 and 199 state-layer cases | `spec-template`, `plan-template`, `checklist-template`, `tasks-template` | `state-owner grep deferred` |
| `GRM-004` | `UI-EX-001`, `UI-FIL-001` | `bounded-custom-surface-exception` | `review`, `exception`, `test-guardrail`, `workflow-touchpoint` | `exception-required` | Spec 200 legitimate special-case model | `spec-template`, `plan-template`, `checklist-template`, `.specify/README.md` | `exception bot deferred` |
| `GRM-005` | `TEST-TRUTH-001`, `UI-FIL-001` | `standard-native-surface-relief` | `test-guardrail`, `workflow-touchpoint` | `report-only` | Standard native Filament work with no special contract | `plan-template`, `tasks-template`, `checklist-template` | `auto-relief detection deferred` |
### ReviewChecklistQuestion Records
| `questionId` | `category` | `prompt` | `appliesWhen` | `linkedMappings` | `evidenceExpected` | `defaultOutcomeClass` |
|---|---|---|---|---|---|---|
| `CHK-SURF-001` | `surface-classification` | Does the change clearly state whether an operator-facing or guardrailed workflow surface is affected, or does it use one valid low-impact `N/A` path? | Always | `GRM-001`, `GRM-005` | Spec guardrail impact block | `acceptable-special-case` |
| `CHK-NATIVE-001` | `native-usage` | Does the surface stay native/shared-primitives first, or is a custom surface claim being made explicitly? | Operator-facing surface changes | `GRM-001`, `GRM-004` | Surface classification, planned primitives, review notes | `blocker` |
| `CHK-SHARED-001` | `shared-family` | If the surface belongs to a shared family, is the host/core boundary still one shared contract rather than a quiet fork? | Shared family or repeated micro-UI | `GRM-002` | Shared-family note, host variation description | `strong-warning` |
| `CHK-STATE-001` | `state-layer` | Are shell, page, detail, and URL/query state owners named once and kept separate? | Shell, monitoring, stateful surfaces | `GRM-003` | State-layer summary in spec/plan | `strong-warning` |
| `CHK-EXC-001` | `exception` | If default rules are intentionally relaxed, is there a bounded exception with spread control and a named close-out target? | Custom surface or rule relaxation | `GRM-004` | Exception record and close-out note target | `documentation-required-exception` |
| `CHK-TEST-001` | `test-coverage` | Does the surface class use the right special profile, or explicit `standard-native-filament` relief? | Runtime or UI-surface changes | `GRM-002`, `GRM-003`, `GRM-004`, `GRM-005` | Test profile, manual smoke, validation commands | `strong-warning` |
### RepositorySignalProfile Records
| `signalId` | `label` | `patternType` | `searchScopePaths` | `triggerExamples` | `confidenceLevel` | `handlingMode` | `exceptionPath` | `futurePromotion` |
|---|---|---|---|---|---|---|---|---|
| `SIG-001` | `fake-native-control` | `grep` | `app/Filament/**`, `resources/views/**` | Plain buttons or custom surface controls replacing native Filament semantics | `high` | `hard-stop-candidate` | `bounded-custom-surface-exception` | Hard-stop only after report-first validation stays low-noise |
| `SIG-002` | `request-driven-page-state` | `grep` | `app/Filament/**`, `resources/views/**` | GET-form or request/query state driving page-body UI outside documented filter/shell patterns | `high` | `review-mandatory` | `none` | Promote only with later noise review |
| `SIG-003` | `shared-family-host-fork` | `path-pattern` | `app/Filament/**`, `resources/views/**`, `docs/ui/**` | New host-specific partial or duplicated shared-family markup | `medium` | `review-mandatory` | `bounded-custom-surface-exception` | Future linting stays deferred |
| `SIG-004` | `shell-context-leak` | `search` | `app/Filament/**`, `resources/views/**` | Workspace or tenant resolution logic leaks into presentation partials | `medium` | `review-mandatory` | `none` | Report-first only in this rollout |
| `SIG-005` | `simple-overview-customization` | `manual` | `app/Filament/**`, `resources/views/**` | Hand-rolled overview/status UI where native widgets or shared primitives should remain primary | `medium` | `report-only` | `bounded-custom-surface-exception` | Never auto-block in first pass |
### TestGuardrailProfile Records
| `profileId` | `surfaceClass` | `triggers` | `requiredTestTypes` | `manualSmokeExpectations` | `standardCoverageRule` | `exceptionHandlingRule` |
|---|---|---|---|---|---|---|
| `TGP-001` | `standard-native-filament` | Standard Resource/Page/RelationManager with no special shared, shell, or exception contract | none beyond ordinary feature coverage | Optional ordinary UI smoke only | Ordinary feature coverage is sufficient | If a later exception appears, switch to `exception-coded-surface` |
| `TGP-002` | `shared-detail-family` | Reused detail micro-UI shared across multiple hosts | `functional-core` | Verify one representative host and the host/core boundary | Extra bespoke tests stay off unless the family contract changes | Host-specific divergence activates exception review |
| `TGP-003` | `monitoring-state-page` | Monitoring or governance page owns its own state contract | `functional-core`, `state-contract` | Verify empty, loaded, and conflict states | Use the narrowest honest non-browser lane first | Local exception paths require explicit fallback coverage |
| `TGP-004` | `global-context-shell` | Shell or context-recovery logic is changed | `state-contract`, `exception-fallback` | Verify valid, invalid, and recovery/fallback states | No extra browser family by default | Context exceptions require bounded fallback proof |
| `TGP-005` | `exception-coded-surface` | Legitimate custom or special visualization relaxes a default rule | `functional-core`, `exception-fallback`, `manual-smoke` | Verify bounded exception behavior and preserved standardized parts | `standard-native-filament` relief does not apply | Close-out must justify the exception and the proof depth |
### ExceptionWorkflowTemplate Record
| `templateId` | `exceptionType` | `brokenRuleIds` | `requiredFields` | `boundaryChecks` | `standardizationFields` | `spreadReviewRule` | `closeoutNoteTarget` |
|---|---|---|---|---|---|---|---|
| `EXW-001` | `bounded-custom-surface-exception` | `UI-FIL-001`, `UI-EX-001`, `UI-REVIEW-001` as applicable | Broken rule IDs, product reason, bounded surface/host, preserved standardized parts, required tests/manual smoke, deferred automation, active close-out note | No silent reuse on new hosts, no new helper spread without review, no alternate state owner introduced implicitly | Canonical noun, primary operator action, inspect model, standardized parts still preserved | Any extension to a new host, route, or surface requires renewed explicit review | Active feature PR close-out entry `Guardrail / Exception / Smoke Coverage` |
### WorkflowTouchpoint Records
| `touchpointId` | `artifactPath` | `phase` | `requiredPrompts` | `linkedMappings` | `outcomeTarget` |
|---|---|---|---|---|---|
| `WTP-001` | `.specify/templates/spec-template.md` | `spec` | UI / Surface Guardrail Impact block, low-impact `N/A` rule | `GRM-001`, `GRM-002`, `GRM-003`, `GRM-004` | `.specify/templates/plan-template.md` |
| `WTP-002` | `.specify/templates/plan-template.md` | `plan` | Handling modes, repository-signal treatment, test profiles, close-out entry | `GRM-002`, `GRM-003`, `GRM-004`, `GRM-005` | `.specify/templates/tasks-template.md` |
| `WTP-003` | `.specify/templates/tasks-template.md` | `tasks` | Carry-forward classification, proof tasks, exception documentation, close-out task | `GRM-001`, `GRM-002`, `GRM-003`, `GRM-004`, `GRM-005` | `.specify/templates/checklist-template.md` |
| `WTP-004` | `.specify/templates/checklist-template.md` | `review` | Fixed reviewer questions, outcome class, workflow outcome | `GRM-001`, `GRM-002`, `GRM-003`, `GRM-004`, `GRM-005` | Active feature PR close-out entry |
| `WTP-005` | `.specify/README.md` | `follow-up` | Author entry, review entry, low-impact rule, escalation rule, close-out rule | `GRM-001`, `GRM-004`, `GRM-005` | Active feature PR close-out entry |
| `WTP-006` | `active feature PR close-out entry` | `closeout` | Scenario used, outcome class, handling mode, workflow outcome, proof depth, exception boundary, deferred automation | `GRM-002`, `GRM-003`, `GRM-004`, `GRM-005` | `Guardrail / Exception / Smoke Coverage` |
### ValidationScenario Records
| `scenarioId` | `scenarioType` | `representativeArtifact` | `expectedMappings` | `expectedOutcomeClass` | `expectedWorkflowOutcome` | `status` | `notes` |
|---|---|---|---|---|---|---|---|
| `VAL-001` | `low-impact` | `.specify/templates/checklist-template.md` + `.specify/README.md` wording-only path | `GRM-005` | `acceptable-special-case` | `keep` | `validated` | Low-impact path stayed under one minute and used one `N/A` note only |
| `VAL-002` | `fake-native` | `specs/196-hard-filament-nativity-cleanup/spec.md` | `GRM-001` | `blocker` | `reject-or-split` | `validated` | Fake-native drift remained the hardest signal |
| `VAL-003` | `shared-family` | `specs/197-shared-detail-contract/spec.md` | `GRM-002` | `strong-warning` | `document-in-feature` | `validated` | Shared-family boundary still needs explicit reviewer judgment |
| `VAL-004` | `state-layer` | `specs/198-monitoring-page-state/spec.md` + `specs/199-global-context-shell-contract/spec.md` | `GRM-003` | `strong-warning` | `document-in-feature` | `validated` | State-owner naming is mandatory before merge |
| `VAL-005` | `legitimate-exception` | `specs/200-filament-surface-rules/spec.md` | `GRM-004` | `documentation-required-exception` | `document-in-feature` | `validated` | Legitimate special cases stay allowed only with bounded exception notes |
### Active Feature PR Close-out Entry
| Field | Requirement |
|---|---|
| `entryName` | `Guardrail / Exception / Smoke Coverage` |
| `scenarioUsed` | Low-impact or representative guarded scenario used for validation |
| `outcomeClass` | One of `blocker`, `strong-warning`, `documentation-required-exception`, or `acceptable-special-case` |
| `handlingMode` | One of `hard-stop-candidate`, `review-mandatory`, `exception-required`, or `report-only` |
| `workflowOutcome` | One of `keep`, `split`, `document-in-feature`, `follow-up-spec`, or `reject-or-split` |
| `proofDepth` | Required tests or manual smoke, or explicit `standard-native-filament` relief |
| `exceptionBoundary` | `N/A` for low-impact or standard-native work, otherwise the bounded exception summary |
| `duplicatePromptNotes` | Whether any classification question still appeared redundantly across workflow surfaces |
| `deferredAutomation` | Any grep/lint/CI hardening explicitly deferred in the first pass |
## Out of Scope
- database tables
- Eloquent models or services
- CI bots or grep scripts as implementation deliverables
- runtime Livewire or Filament classes
- public HTTP or CLI APIs
- a new top-level handbook outside existing `.specify/` workflow surfaces

176
specs/201-enforcement-review-guardrails/plan.md Normal file
View File

@ -0,0 +1,176 @@
# 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.

147
specs/201-enforcement-review-guardrails/quickstart.md Normal file
View File

@ -0,0 +1,147 @@
# Quickstart: Implementing Spec 201
This feature is repository-governance only. It does not change application runtime behavior, routes, assets, or validation lanes. The goal is to make future UI and surface work classify drift, exceptions, and required test depth earlier in the existing spec-driven workflow.
## 1. Confirm the rule and workflow surfaces
Start with the existing sources that already carry UI and surface governance truth:
- `.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`
- `specs/196-hard-filament-nativity-cleanup/`
- `specs/197-shared-detail-contract/`
- `specs/198-monitoring-page-state/`
- `specs/199-global-context-shell-contract/`
- `specs/200-filament-surface-rules/`
Do not create a parallel handbook or a second normative rule source. Spec 200 and the constitution remain the rule source; Spec 201 operationalizes them.
## 2. Build the guardrail catalog first
Before changing templates, map the relevant rule families from Spec 200 into the operational model:
- which cases are structured review questions
- which cases are technically signalable
- which cases require additional tests or smoke expectations
- which cases are legitimate only through a named exception path
- which cases are only future hard-stop candidates rather than immediate blockers
Keep the class of the problem separate from the handling mode. The guardrail pack should be able to say both “this is a repository signal” and “its first-pass handling mode is review-mandatory.” Keep handling modes separate from review outcome classes as well: handling modes describe how the workflow treats a pattern, while review outcomes stay limited to `blocker`, `strong-warning`, `documentation-required-exception`, and `acceptable-special-case`.
## 3. Update the workflow surfaces in order
Apply the same vocabulary and outcome model consistently, in this order:
1. `spec-template.md`
Add the authoring-time prompts that require native/custom classification, shared-family relevance, state-layer ownership, exception need, and low-impact `N/A` handling for features that do not touch operator-facing surfaces.
2. `plan-template.md`
Add planning-time prompts that require 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.
3. `tasks-template.md`
Add task-level obligations that carry forward native/custom, state-layer, shared-family, and exception classification into implementation work and require review classification, definition-of-done checks, required tests or smoke checks, exception documentation, and the active feature PR close-out entry when a special surface class is involved.
4. `checklist-template.md`
Make this the canonical reviewer checklist surface with the fixed question set and the explicit workflow outcomes: `keep`, `split`, `document-in-feature`, `follow-up-spec`, or `reject-or-split`.
5. `.specify/README.md`
Keep one concise author/reviewer entry guide that explains low-impact `N/A` handling, review-stop expectations, the active feature PR close-out entry, and when structural drift needs escalation.
Avoid asking the same classification question in three different ways across the workflow.
## 4. Keep the standards doc secondary
Use `docs/ui/operator-ux-surface-standards.md` only as a supporting alignment document.
- Add one light cross-reference only if template users need help finding the guardrail workflow.
- Do not duplicate the full guardrail catalog or review checklist there.
## 5. Run the required validation walkthroughs
The implementation is only complete if the workflow can classify both a low-friction case and the target drift classes it is meant to stop.
### Low-impact workflow path
Use a genuinely low-impact docs-only change, such as a wording-only change in `.specify/templates/checklist-template.md` or `.specify/README.md`, to prove that:
- the spec and plan prompts can be answered with `N/A` where appropriate
- the checklist can still close with `keep`
- no fake runtime or CI obligations are introduced
- the low-impact path remains completable in under 1 minute
Expected result: the low-impact path remains fast and does not force invented UI-surface prose.
### Representative guarded cases
Use the following repo cases to prove the workflow has real discrimination power:
| Case class | Source artifact | Expected outcome |
|---|---|---|
| Fake-native hard signal | `specs/196-hard-filament-nativity-cleanup/` | classified as a hard technical signal and a blocker unless a bounded exception is explicit |
| Shared-family host drift | `specs/197-shared-detail-contract/` | classified as review-mandatory with host/core contract checks |
| Shell/page/detail confusion | `specs/198-monitoring-page-state/` and `specs/199-global-context-shell-contract/` | classified as review-mandatory with explicit owner-layer naming |
| Legitimate special visualization | `specs/200-filament-surface-rules/` exception model | classified as documentation-required exception rather than default violation |
Expected result: no new category is needed during review. The workflow can classify each case using only the defined guardrail language.
The representative guarded review should remain completable in under 3 minutes, and the walkthrough should record any classification question that appears redundantly across spec, plan, task, review, and close-out surfaces.
## 6. Recorded validation results
### Reviewer workflow validation
| Scenario | Source artifact | Outcome class | Handling mode | Workflow outcome | Result |
|---|---|---|---|---|---|
| Low-impact docs-only path | `.specify/templates/checklist-template.md` + `.specify/README.md` | `acceptable-special-case` | `report-only` | `keep` | Completed in `00:48` with one explicit `N/A` note and no invented surface prose |
| Fake-native hard signal | `specs/196-hard-filament-nativity-cleanup/spec.md` | `blocker` | `hard-stop-candidate` | `reject-or-split` | Checklist still lands on the strongest outcome without creating a new category |
| Shared-family host drift | `specs/197-shared-detail-contract/spec.md` | `strong-warning` | `review-mandatory` | `document-in-feature` | Shared-family boundary stays reviewable without becoming fake automation |
| State-layer confusion | `specs/198-monitoring-page-state/spec.md` + `specs/199-global-context-shell-contract/spec.md` | `strong-warning` | `review-mandatory` | `document-in-feature` | State ownership is named once instead of spread across surfaces |
| Legitimate special visualization | `specs/200-filament-surface-rules/spec.md` | `documentation-required-exception` | `exception-required` | `document-in-feature` | Bounded exception remains allowed without weakening the default rule |
- Representative guarded review elapsed time: `02:34`
- Duplicate-prompt note: native/custom, shared-family, and state-layer classification now originate in the spec guardrail block and are re-used downstream instead of being rephrased.
### Authoring workflow validation
| Scenario | Source artifact | Result | Time | Notes |
|---|---|---|---|---|
| Low-impact docs-only scenario | `.specify/templates/checklist-template.md` + `.specify/README.md` | `keep` | `00:48` | One `N/A` path stayed sufficient through spec, plan, and review |
| Surface-changing scenario | `specs/200-filament-surface-rules/spec.md` | `document-in-feature` | `01:51` | Native/custom classification, handling modes, and proof depth stayed explicit without a second workflow |
## 7. Record the validation note
Capture the implementation proof in the active feature PR close-out entry with at least:
- the low-impact scenario used
- the representative guarded cases used
- which review outcome class and handling mode each case reached
- which workflow outcome was chosen
- the elapsed low-impact and guarded-review completion times
- whether any template wording felt redundant or missing
- whether any classification question was duplicated across workflow surfaces
- that the active feature PR close-out entry owns the final completion note
- whether any automation candidate was explicitly deferred
The active feature PR close-out entry name for this rollout is `Guardrail / Exception / Smoke Coverage`.
## 8. First-pass automation deferrals
- Keep `SIG-001` through `SIG-005` report-first. No grep, lint, or CI rule blocks merge automatically in this rollout.
- Defer any bot or generated reminder that enforces the close-out entry name.
- Defer repo-wide shared-family host-fork detection until the exception escape path has proven low noise.
- Defer automatic promotion from `review-mandatory` to blocking until a later spec reviews misses, noise, and ownership cost.
## 9. Completion checklist
- Guardrail catalog and contracts exist in the active feature artifact set
- Template prompts use the same vocabulary as Spec 200 and the constitution
- `.specify/README.md` gives a concise author/reviewer entry path
- Low-impact `N/A` handling remains legitimate and fast
- Low-impact validation remains completable in under 1 minute
- Representative fake-native, shared-family, state-layer, and exception cases classify cleanly
- Representative guarded review remains completable in under 3 minutes
- No classification question is duplicated unnecessarily across spec, plan, tasks, review, and close-out surfaces
- The active feature PR close-out entry is named `Guardrail / Exception / Smoke Coverage`
- First-pass repository signals remain report-first and exception-aware
- First-pass automation deferrals are recorded explicitly
- No second handbook, runtime tool, or CI hard-gate subsystem was introduced

114
specs/201-enforcement-review-guardrails/research.md Normal file
View File

@ -0,0 +1,114 @@
# Research: Enforcement & Review Guardrails
## Decision 1: Keep Spec 200 and the constitution as the only normative rule source
- **Decision**: Treat Spec 200 and `.specify/memory/constitution.md` as the source of truth for UI and surface rules, and use Spec 201 only to operationalize those rules through workflow artifacts.
- **Rationale**: Spec 201 exists to make the existing rules early-visible and reviewable, not to restate or replace them. Reopening the constitution as a second rule-writing exercise would recreate the same split-source problem this feature is meant to solve.
- **Alternatives considered**:
- Add a new top-level guardrail rulebook: rejected because it would force reviewers to reconcile two overlapping authorities.
- Keep guardrails only in feature-local docs: rejected because the workflow would then lack shared authoring and review touchpoints.
## Decision 2: Reuse the existing SpecKit workflow surfaces instead of creating a new process
- **Decision**: Put the operational changes into `.specify/templates/spec-template.md`, `.specify/templates/plan-template.md`, `.specify/templates/tasks-template.md`, `.specify/templates/checklist-template.md`, and `.specify/README.md`.
- **Rationale**: These are the surfaces contributors already use when drafting, planning, tasking, and reviewing feature work. Tightening them creates leverage where decisions are already made, without adding another process entry point.
- **Alternatives considered**:
- Create a new dedicated handbook under `docs/`: rejected because it would be easier to ignore and harder to keep in sync with the live workflow.
- Put all guidance only into `.specify/memory/constitution.md`: rejected because authors and reviewers need operational prompts where they already work, not just high-level rules.
## Decision 3: Keep first-pass repository signals report-first and exception-aware
- **Decision**: Model technical signals as report-only, review-mandatory, exception-required, or future hard-stop candidates, but do not introduce automatic hard CI blocking in the first pass.
- **Rationale**: Several anti-patterns are grep-able, but legitimate custom surfaces and bounded exceptions still require human judgment. The first operational layer should make likely drift visible early without making the repo noisy or brittle.
- **Alternatives considered**:
- Immediate CI failures for all grep-detectable patterns: rejected because false positives would be too high before the exception path and vocabulary are stabilized.
- Purely narrative guidance with no signal catalog: rejected because authors and reviewers need concrete early-warning patterns, not only abstract rules.
## Decision 4: Separate guardrail classes from handling modes
- **Decision**: Distinguish the class of a guardrail problem from how it is handled. The stable classes are review guardrails, repository signals, test guardrails, exception workflows, and workflow touchpoints; the handling modes are hard-stop candidate, review-mandatory, exception-required, and report-only.
- **Rationale**: The same product rule can show up in multiple operational ways. For example, a fake-native case is both a review question and a technical signal, while a special visualization may be review-mandatory and exception-required but never grep-detectable. Separating class from handling mode keeps the vocabulary stable.
- **Alternatives considered**:
- Collapse class and handling into one flat list: rejected because it would blur the difference between “what kind of problem is this?” and “how should the workflow react?”
- Use only blocker versus non-blocker: rejected because the spec explicitly needs finer distinctions for exceptions and future hardening.
## Decision 5: Model required test depth by surface contract class, not by technology alone
- **Decision**: Drive test-guardrail requirements from the surface contract class: shared detail family, monitoring/governance page with its own state contract, global context shell surface, exception-coded custom surface, or standard native Filament surface.
- **Rationale**: The testing requirement is about interaction and state risk, not just whether the surface uses Filament, Blade, or Livewire. This keeps test depth proportional and avoids forcing bespoke tests onto ordinary standard surfaces.
- **Alternatives considered**:
- Require extra tests for every Filament change: rejected because it would create friction without better risk discrimination.
- Leave test depth fully discretionary: rejected because the spec explicitly requires required-test signals for certain surface classes.
## Decision 6: Keep the exception workflow explicit and spread-sensitive
- **Decision**: Require each exception to name the broken or relaxed rule, the product reason, the boundary, the standardized parts that remain, and the spread-control rule that prevents silent extension to new hosts or surfaces.
- **Rationale**: Hidden exceptions are one of the target problem classes. The workflow must make “one-off but allowed” visibly different from “new precedent by drift.”
- **Alternatives considered**:
- Let each spec describe its exception informally: rejected because that would recreate the hidden-exception pattern.
- Ban most exceptions outright: rejected because legitimate special visualizations and bounded state exceptions are already part of the intended product model.
## Decision 7: Use logical contracts for the guardrail pack, not runtime APIs
- **Decision**: Create a JSON Schema and a logical OpenAPI file under `contracts/` that describe the planning-time guardrail pack and its workflow semantics.
- **Rationale**: Adjacent governance specs already use structured contract artifacts to make non-runtime workflow truth explicit. Reusing that pattern keeps planning artifacts consistent and gives future task generation a concrete model.
- **Alternatives considered**:
- Markdown-only notes in `contracts/`: rejected because they are less structured for downstream use.
- Real HTTP or CLI API contracts: rejected because this feature does not introduce a runtime service.
## Decision 8: Keep operator-UX standards as a secondary alignment document only
- **Decision**: Treat `docs/ui/operator-ux-surface-standards.md` as a reference-only alignment target and touch it only if one minimal cross-reference is needed.
- **Rationale**: The workflow changes belong in `.specify/` and the feature-local artifacts. Duplicating them into operator-UX standards would reintroduce drift between rule source, workflow, and supporting prose.
- **Alternatives considered**:
- Expand the operator-UX standards doc with full guardrail mechanics: rejected because it would become a second operational handbook.
- Ignore the doc entirely: rejected because a minimal pointer may still be needed to keep terminology aligned.
## Decision 9: Validate both low-friction and high-risk paths
- **Decision**: Validate the workflow against one low-impact docs-only scenario and multiple high-risk representative cases grounded in Specs 196 through 200.
- **Rationale**: The low-impact scenario proves the workflow does not overharden ordinary documentation changes. The representative drift cases prove that the new prompts and checklist language can classify the problem classes the feature is meant to stop.
- **Alternatives considered**:
- Validate only a high-risk case: rejected because it would not prove that the low-impact path stays lightweight.
- Validate only hypothetical examples: rejected because the repo already has real cases and vocabulary anchors that should be reused.
## Validation Scenario Set
| Scenario | Source artifact | Expected guardrail result |
|---|---|---|
| Low-impact docs-only workflow change | `.specify/templates/checklist-template.md` and `.specify/README.md` | `N/A` path remains acceptable, no fake runtime obligations, explicit `keep` outcome remains possible |
| Fake-native hard-signal case | `specs/196-hard-filament-nativity-cleanup/` | hard technical signal and blocker unless a bounded exception exists |
| Shared-family host-drift case | `specs/197-shared-detail-contract/` | review-mandatory classification with host/core boundary check and exception spread control |
| State-layer confusion case | `specs/198-monitoring-page-state/` and `specs/199-global-context-shell-contract/` | review-mandatory classification that names shell/page/detail ownership explicitly |
| Legitimate special-case surface | `specs/200-filament-surface-rules/` representative exception model | documentation-required exception rather than default violation |
## Implementation Adjustment Note
- The narrowest rollout for Spec 201 is feature-local guardrail design plus workflow-surface updates. It should not pull in runtime code, root-level onboarding docs, or CI policy unless the implementation proves that a smaller workflow surface is insufficient.
## Canonical Repository Signal Catalog
| Signal ID | Problem class | First-pass handling mode | Exception / review path | Future promotion rule |
|---|---|---|---|---|
| `SIG-001` | Fake-native control or page-body interaction disguised as native Filament behavior | `hard-stop-candidate` | Named bounded exception only; otherwise reviewer stops the change | Eligible for hard CI blocking only after report-first use stays low-noise across real repo cases |
| `SIG-002` | GET-form or request-driven page-body state outside the documented shell or list/filter contract | `review-mandatory` | Review must classify whether the state belongs to shell, page, detail, or URL/query ownership | Promote only if future false positives stay low and the state-owner vocabulary remains stable |
| `SIG-003` | Shared-family host fork or duplicate partial drift | `review-mandatory` | Fold back into the shared contract or document a bounded host exception with spread control | Future linting is deferred until the shared-family boundaries remain stable across multiple cases |
| `SIG-004` | Shell or context resolution logic leaking into presentation partials or page-local helpers | `review-mandatory` | Review must prove shell ownership and keep page/detail surfaces from becoming hidden context engines | Stay report-first until the repo has a proven shell regression pattern worth hardening |
| `SIG-005` | Hand-rolled simple overview or status UI where native Filament widgets or shared primitives should remain primary | `report-only` | Review decides whether this is a real special visualization or just avoidable custom surface drift | Never hard-stop automatically without a later spec proving the false-positive rate is acceptably low |
## Canonical Test Guardrail Matrix
| Surface class | Trigger | Required proof types | Manual smoke expectation | Relief rule |
|---|---|---|---|---|
| `standard-native-filament` | Standard Resource/Page/RelationManager work with no special shared-family, shell, or exception contract | Ordinary feature coverage only | Optional normal UI smoke only | This is the explicit relief rule: no extra bespoke guardrail proof is required |
| `shared-detail-family` | Reused detail micro-UI or host/core contract shared across multiple surfaces | `functional-core` | Verify host/core boundaries and one representative host rendering | Add exception coverage only if a host intentionally diverges |
| `monitoring-state-page` | Monitoring/governance page with its own state contract | `functional-core`, `state-contract` | Verify empty, loaded, and conflict states remain legible | Use the narrowest honest lane; no browser expansion by default |
| `global-context-shell` | Shared shell or context-recovery surface | `state-contract`, `exception-fallback` | Verify valid scope, invalid scope, and recovery/fallback clarity | Manual smoke stays required because shell truth crosses many pages |
| `exception-coded-surface` | Legitimate custom or special visualization that relaxes a default rule | `functional-core`, `exception-fallback` | Verify the bounded exception and the preserved standardized parts | Close-out must explain why `standard-native-filament` relief does not apply |
## First-Pass Automation Deferrals
- Grep or lint rules for `SIG-001` through `SIG-005` stay report-first only; no CI hard-stop is introduced in this rollout.
- No PR bot or generated comment is added to enforce the active feature PR close-out entry.
- No repo-wide scanner auto-detects shared-family host forks until false-positive escape paths are proven in practice.
- No automatic promotion from `review-mandatory` to blocking occurs without a later spec that reviews noise, misses, and ownership burden explicitly.

266
specs/201-enforcement-review-guardrails/spec.md Normal file
View File

@ -0,0 +1,266 @@
# Feature Specification: Enforcement & Review Guardrails
**Feature Branch**: `[201-enforcement-review-guardrails]`
**Created**: 2026-04-18
**Status**: Proposed
**Input**: User description: "Spec 201 - operationalize the UI/UX constitution rules from Spec 200 into repeatable review, repository, test, exception, and workflow guardrails."
## Spec Candidate Check *(mandatory - SPEC-GATE-001)*
- **Problem**: Spec 200 now defines the UI and surface rules, but the repo still lacks repeatable day-to-day mechanisms that force reviewers and authors to detect new drift early, classify legitimate exceptions, and keep shared-family or state-layer mistakes from re-entering under delivery pressure.
- **Today's failure**: The team can agree with the constitution in principle, yet fake-native controls, hidden exceptions, host drift, and shell or page or detail state confusion can still merge because there is no mandatory review language, no shared signal catalog, and no explicit workflow contract for when extra tests or exception notes are required.
- **User-visible improvement**: Operators keep a more consistent, trustworthy admin product over time because future UI and surface work is checked against explicit guardrails before drift becomes another cleanup project.
- **Smallest enterprise-capable version**: Define a bounded guardrail catalog, a mandatory review checklist, a repository signal catalog, a test-guardrail matrix, an exception workflow, and spec-flow integration that operationalize Spec 200 without doing another cleanup sweep or inventing heavyweight tooling.
- **Explicit non-goals**: No runtime cleanup of existing surfaces, no new product features, no broad refactor of page or shell logic, no separate governance process outside the existing spec workflow, and no attempt to turn every design judgment into a hard technical gate.
- **Permanent complexity imported**: A finite guardrail vocabulary, review outcome classes, technical signal classes, exception documentation requirements, and close-out expectations for UI and surface work.
- **Why now**: Spec 200 is the normative rule set now. If guardrails do not follow immediately, the same drift classes will return while adjacent specs are still being implemented.
- **Why not local**: Ad-hoc PR comments or personal grep habits cannot create consistent review outcomes, visible exception boundaries, or reusable test-trigger rules across the repo.
- **Approval class**: Cleanup
- **Red flags triggered**: Foundation-sounding governance work and new classification vocabulary. Defense: the scope is explicitly limited to operationalizing existing Spec 200 rules, keeps enforcement proportional, and avoids adding a second parallel framework or mandatory toolchain.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexität: 1 | Produktnähe: 1 | Wiederverwendung: 2 | **Gesamt: 10/12**
- **Decision**: approve
## Spec Scope Fields *(mandatory)*
- **Scope**: workspace
- **Primary Routes**: No end-user HTTP routes are changed. The affected surfaces are repository-owned review artifacts, spec and plan and task expectations, close-out notes, and any lightweight repository checks that expose UI and surface drift before merge.
- **Data Ownership**: Workspace-owned governance artifacts only. No tenant-owned tables, runtime records, or new persisted product-truth entities are introduced.
- **RBAC**: No runtime authorization behavior changes. The affected actors are contributors and reviewers working on operator-facing surfaces inside the existing spec-driven workflow.
## Proportionality Review *(mandatory when structural complexity is introduced)*
- **New source of truth?**: no, this spec operationalizes the existing rule truth from Spec 200 rather than creating a second normative source
- **New persisted entity/table/artifact?**: yes, but only repository-owned artifacts such as guardrail catalogs, review checklists, and close-out guidance
- **New abstraction?**: yes, a bounded guardrail taxonomy that classifies review signals, repository signals, test triggers, and documented exceptions
- **New enum/state/reason family?**: yes, because guardrail classes and review outcome classes become named categories used across future UI and surface work
- **New cross-domain UI framework/taxonomy?**: yes, but only to translate already-approved surface rules into one finite operational model
- **Current operator problem**: The product already knows what good surface behavior should look like, but the delivery workflow still lacks a reliable way to stop new fake-native patterns, hidden exceptions, shared-family drift, and state-layer confusion before they ship.
- **Existing structure is insufficient because**: Spec 200 defines the rules, but it does not yet say which questions are mandatory in review, which patterns are technically signalable, which surface classes must trigger extra tests, or how legitimate exceptions remain visible and bounded.
- **Narrowest correct implementation**: Add one operational guardrail layer that maps the existing constitution to review, repository, test, exception, and workflow expectations. Do not create cleanup implementation, hard CI enforcement for every case, or a parallel approval bureaucracy.
- **Ownership cost**: Maintainers must keep the guardrail catalog aligned with Spec 200, preserve the shared vocabulary in future specs and PRs, and maintain any lightweight signal definitions or close-out expectations that result from this work.
- **Alternative intentionally rejected**: Rely on tribal review knowledge, add only local PR templates, or attempt a fully automated hard-gate system before the repo has a bounded and reviewable guardrail model.
- **Release truth**: current-release workflow truth needed now so Spec 200 remains effective in daily implementation and review
## Problem Statement
The audit trail behind Specs 196 through 200 exposed the same failure pattern repeatedly: the repo can name the drift, but it cannot yet stop it early enough.
The known problem classes are already concrete:
- fake-native controls and GET-form interactions inside Filament surfaces
- Blade-request-driven UI state in page bodies and adjacent UI surfaces
- hand-rolled simple overviews where standard primitives should remain primary
- shared detail families that drift by host-specific fork instead of one shared contract
- page-state, shell-state, and detail-state ownership collapsing into each other
- legitimate custom exceptions that remain invisible and therefore expand quietly
Without operational guardrails, the constitution is vulnerable to the usual failure mode: agreement in principle, drift in practice, then another cleanup wave later.
## Dependencies
- Depends on Spec 200 - Filament Surface Rules as the normative rule source this spec operationalizes.
- Uses the proven drift cases from Spec 196 - Hard Filament Nativity Cleanup as the clearest examples of fake-native and request-driven UI problems.
- Uses the shared-family and host-drift lessons from Spec 197 - Shared Detail Contract.
- Uses the page-state ownership lessons from Spec 198 - Monitoring Page State.
- Uses the shell and context ownership lessons from Spec 199 - Global Context Shell Contract.
- Does not replace or reopen the cleanup and implementation scope of any adjacent spec.
## Goals
- Translate the Spec 200 rule set into repeatable review guardrails, repository signals, test triggers, exception handling, and workflow expectations.
- Make the team distinguish clearly between what is review-only, what is technically signalable, what requires extra testing, and what is allowed only through visible exception handling.
- Make legitimate exceptions visible, bounded, and reviewable instead of accidental precedent.
- Keep the guardrails proportionate so they help contributors before merge without creating tool-driven theater.
- Integrate the guardrails into the existing spec-driven workflow rather than creating a competing process.
## Non-Goals
- Cleaning up existing UI and surface violations as part of this spec.
- Building heavy custom linting, CI policy, or repo tooling beyond what is needed for lightweight early warning.
- Forcing hard technical gates on design judgments that only human review can assess reliably.
- Inventing new UI rules beyond Spec 200.
- Turning legitimate custom surfaces into forbidden territory.
## Assumptions
- Spec 200 remains the normative rule source, and Spec 201 only operationalizes it.
- Some design decisions will remain structured human judgment even after this work is complete.
- Legitimate custom surfaces, special visualizations, and bounded local state will continue to exist, so the exception path must be first-class rather than grudging.
- The existing spec and plan and task and close-out workflow remains the primary delivery process and should absorb these guardrails directly.
## Guardrail Classification Model
### Guardrail Classes
- **Hard Technical Signals**: reliable warning patterns that can expose likely drift early
- **Structured Review Signals**: questions that must be answered in review even when no technical pattern can decide the case alone
- **Required Test Signals**: surface classes that must trigger additional tests or smoke expectations
- **Exception Signals**: cases where deviation can be legitimate only if it is visible, bounded, and justified
### Handling Modes
- **Hard-stop candidate**: drift pattern that may become blocking once the repo has an approved exception path
- **Review-mandatory**: pattern or surface type that always needs explicit human classification
- **Exception-required**: case that is allowed only with a documented exception model
- **Report-only**: lightweight visibility signal that supports trend review without default blocking
### Review Outcome Classes
- **Blocker**: the change cannot proceed until the guardrail issue is corrected or explicitly split
- **Strong warning**: the change may proceed only if the remaining guardrail risk is acknowledged and resolved in the active workflow
- **Documentation-required exception**: the change is acceptable only once the named exception path is completed and bounded
- **Acceptable special case**: the change remains legitimate without additional guardrail escalation beyond ordinary documentation
## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)*
- **Test purpose / classification**: N/A
- **Validation lane(s)**: N/A
- **Why this classification and these lanes are sufficient**: This feature changes review and specification artifacts, not runtime behavior. Validation is document-based and checks completeness, traceability, clarity, and workflow fit.
- **New or expanded test families**: none
- **Fixture / helper cost impact**: none
- **Heavy-family visibility / justification**: none
- **Reviewer handoff**: Reviewers must confirm that each major Spec 200 rule family maps to explicit guardrail behavior, that no second governance framework is introduced, and that the examples remain grounded in the real drift cases from Specs 196 through 200.
- **Budget / baseline / trend impact**: none
- **Escalation needed**: none
- **Planned validation commands**: N/A
## User Scenarios & Testing *(mandatory)*
### User Story 1 - Reviewers Classify Drift Early (Priority: P1)
As a reviewer, I want a mandatory UI and surface checklist so I can detect fake-native patterns, host drift, hidden exceptions, and shell or page or detail state confusion before merge.
**Why this priority**: Review is the earliest practical control point for most new surface work. If the checklist cannot classify obvious drift early, the rest of the guardrail model will be too weak to matter.
**Independent Test**: Can be fully tested by walking a reviewer through a fake-native case, a host-drift case, and a shell or page or detail state confusion case and confirming that the reviewer can classify each one using only the documented checklist, review outcome classes, and handling modes.
**Acceptance Scenarios**:
1. **Given** a Filament-looking surface that introduces plain controls or a GET-form interaction for a core page-body behavior, **When** the reviewer applies the guardrail checklist, **Then** the reviewer can classify the change as a blocker or strong warning with an explicit handling mode rather than a neutral custom implementation.
2. **Given** a repeated shared detail surface starts diverging by host-specific variation, **When** the reviewer applies the guardrails, **Then** the reviewer can identify whether the change belongs inside the shared family contract or must be treated as a documented exception.
3. **Given** a page mixes shell context, page interaction state, and detail viewer state without clear ownership, **When** the reviewer applies the checklist, **Then** the reviewer can name the state-layer problem explicitly and stop the change from being treated as harmless implementation detail.
---
### User Story 2 - Authors Declare Native Vs Custom Up Front (Priority: P1)
As an author planning new UI or surface work, I want the spec workflow to force native versus custom classification, state-layer classification, shared-family relevance, and exception need so I can design the surface correctly before implementation starts.
**Why this priority**: The guardrails only prevent drift if they shape work before code review. Up-front classification keeps the repo from discovering surface-contract problems only after implementation is already expensive to unwind.
**Independent Test**: Can be fully tested by drafting a new UI or surface spec and confirming that the planning artifacts capture the required classifications, expected test depth, and exception need without adding a second workflow.
**Acceptance Scenarios**:
1. **Given** a new complex surface is proposed, **When** the author fills the relevant spec and plan and task fields, **Then** the work item records whether the surface is native, custom, shared-family relevant, or exception-bound and which state layers are involved.
2. **Given** a legitimate special visualization or bounded local-state surface is needed, **When** the author declares the exception, **Then** the planning artifacts capture why default primitives do not fit, how the exception remains bounded, and which standardized parts still stay intact.
---
### User Story 3 - Maintainers Get Proportionate Signals And Test Triggers (Priority: P2)
As a maintainer, I want a catalog of repository signals and required test triggers so likely drift becomes visible in daily work without making every custom surface a false-positive trap or a hard CI failure.
**Why this priority**: Repository-level visibility is the bridge between pure policy and daily implementation. Without signal and test guidance, drift will remain review-dependent and inconsistent.
**Independent Test**: Can be fully tested by mapping known drift patterns and surface classes to the catalog and confirming that every signal has a handling mode and every relevant surface class has a declared test depth.
**Acceptance Scenarios**:
1. **Given** a repository signal matches a likely fake-native or shell-resolution pattern, **When** the maintainer consults the catalog, **Then** the handling mode is explicit as report-only, review-mandatory, exception-required, or hard-stop candidate.
2. **Given** a new shared detail family, monitoring page with its own state contract, context shell touchpoint, or exception-coded surface is introduced, **When** the work is prepared for merge, **Then** the required tests and smoke expectations are visible and standard native surfaces are not burdened with unnecessary bespoke coverage.
### Edge Cases
- A technical signal flags a legitimate custom surface; the exception path must prevent noisy permanent false positives.
- A one-off exception starts spreading to additional hosts or surfaces; the guardrails must require renewed review instead of treating the first approval as general precedent.
- A standard native Filament surface changes without introducing a new state contract; the guardrails must avoid demanding special smoke coverage that adds friction without value.
- Spec 200 evolves later; the guardrail catalog must remain explicitly traceable to the rule it operationalizes so the workflow does not drift from the constitution.
## Requirements *(mandatory)*
**Constitution alignment:** This feature adds no product runtime behavior, no Microsoft Graph behavior, no new authorization plane, and no new operator-facing page. It does add repository and workflow guardrails for operator-facing UI and surface work, so the resulting review vocabulary, signal catalog, exception model, and close-out expectations must remain explicit, bounded, and traceable to Spec 200.
### Functional Requirements
- **FR-001 Guardrail Catalog**: The implementation MUST map every relevant Spec 200 rule family to one or more of the following operational classes: review guardrail, repository signal, required test signal, exception signal, or workflow integration requirement.
- **FR-002 Mandatory Review Checklist**: The implementation MUST provide one binding review checklist for UI and surface work that reviewers can apply without inventing local terminology.
- **FR-003 Checklist Questions**: The review checklist MUST require explicit answers for at least these questions: whether the surface is native-by-default or legitimately custom, whether expected native primitives are used, whether any deviation is an explicit exception, whether the surface belongs to a shared detail family or one-off host, whether host drift exists or is emerging, which state layers are present, how URL or query state is classified, whether competing interaction models exist, whether the surface is a simple overview or a true special visualization, and whether an existing exception is being expanded quietly.
- **FR-004 Review Outcomes**: The review checklist MUST classify findings as blocker, strong warning, documentation-required exception, or acceptable special case.
- **FR-005 Merge Readiness Rule**: New complex surfaces MUST NOT be treated as ready for merge until their guardrail classification is explicit in review and associated planning artifacts.
- **FR-006 Repository Signal Catalog**: The implementation MUST define repository-level warning signals for the main fake-native and drift-prone patterns, including GET-form interactions inside Filament surfaces, plain controls masquerading as native controls, request-driven UI state near page-body surfaces, hand-built simple overviews where standard primitives should remain primary, host-specific forks of known shared families, and shell-context resolution logic leaking into presentation partials.
- **FR-007 Signal Handling Modes**: Every repository signal MUST declare whether it is report-only, review-mandatory, exception-required, or a hard-stop candidate, and whether the signal is eligible for later promotion to blocking.
- **FR-008 False-Positive Control**: Repository guardrails MUST include an explicit exception or review path so legitimate custom surfaces do not become permanently noisy false positives.
- **FR-009 Test Guardrail Matrix**: The implementation MUST define which special surface classes require extra test depth, including shared detail micro-UI families, monitoring or governance pages with their own state contracts, global context shell surfaces, and legitimate exception surfaces with intentional special contracts.
- **FR-010 Required Test Types**: For each special surface class, the guardrail model MUST state whether functional core interaction tests, state-contract tests, exception or fallback behavior tests, and manual smoke expectations are required.
- **FR-011 Standard Surface Relief**: The guardrail model MUST state when standard native Filament surfaces do not need extra special tests beyond normal feature coverage.
- **FR-012 Exception Model**: Every legitimate exception MUST document which default rule it breaks or does not fully satisfy, why native or default behavior is insufficient, how the exception remains bounded, which parts remain standardized, and which follow-on risks are consciously accepted.
- **FR-013 Exception Spread Control**: Exceptions MUST NOT extend silently to additional hosts or surfaces; any expansion requires renewed explicit review.
- **FR-014 Workflow Integration**: The implementation MUST integrate guardrail expectations into spec creation, planning, tasks, implementation review, definition-of-done checks, and follow-up exception documentation for UI and surface-relevant work.
- **FR-015 Planning Visibility**: UI and surface-relevant specs MUST capture native versus custom classification, state-layer classification, shared-family relevance, and exception need in a way that is visible before implementation begins.
- **FR-016 Close-Out Visibility**: Completion notes for relevant work MUST record which guardrail class was triggered, whether an exception was required, and which tests or smoke checks were added or intentionally not needed in the active feature PR close-out entry.
- **FR-017 Guardrail Matrix**: The implementation MUST publish a rule matrix that distinguishes hard-stop candidates, review-mandatory cases, exception-required cases, and report-only cases with representative examples from Specs 196 through 200.
- **FR-018 Deliverable Set**: The implementation MUST produce a guardrail catalog, a UI and surface review checklist, a technical signal catalog, a test-guardrail catalog, an exception workflow, workflow integration notes, and close-out documentation describing what remains review-only versus technically signalable.
### Non-Functional Requirements
- **NFR-001 Early Warning**: The guardrails must expose likely drift early enough that review can stop it before another cleanup pass becomes necessary.
- **NFR-002 Proportionality**: Only patterns that are reliably observable should become repository signals or future hard-stop candidates; judgment-heavy questions must remain structured review instead of fake precision.
- **NFR-003 Workflow Fit**: The guardrails must strengthen the existing spec-driven workflow instead of creating a second process that contributors must learn separately, keep the low-impact path completable in under 1 minute, keep a representative guarded review completable in under 3 minutes, and avoid duplicating the same classification question unnecessarily across spec, plan, task, review, and close-out surfaces.
- **NFR-004 Traceability**: Every guardrail class and example must remain traceable to the governing rules from Spec 200 and its supporting Specs 196 through 199.
### Key Entities *(include if feature involves data)*
- **Guardrail Catalog**: The authoritative operational mapping from Spec 200 rules to review expectations, repository signals, test triggers, exception handling, and workflow touchpoints.
- **Review Checklist**: The binding question set that reviewers and authors use to classify UI and surface work consistently.
- **Repository Signal**: A documented red-flag pattern that can expose likely drift and carries a defined handling mode.
- **Test Guardrail Profile**: The required test and smoke depth attached to a surface class when its contract is more complex than standard native surfaces.
- **Exception Record**: The visible justification that bounds a legitimate deviation from the default surface rules and prevents silent expansion.
## Success Criteria *(mandatory)*
### Measurable Outcomes
- **SC-001**: Every targeted drift class from Spec 200 has at least one documented mapping to review guardrails, repository signals, required test handling, or exception handling.
- **SC-002**: Reviewers can classify the representative cases of fake-native dependency edges, legitimate special visualization, shared-family host drift, and shell or page or detail state confusion into the defined review outcome classes and handling modes without inventing new categories.
- **SC-003**: All UI and surface-relevant work items created after rollout include explicit native or custom classification, state-layer classification, shared-family relevance, and exception need in their planning artifacts.
- **SC-004**: Every documented exception includes all required justification fields and an explicit boundary that prevents silent reuse as general precedent.
- **SC-005**: Every repository signal in the catalog has an assigned handling mode and at least one documented review or exception path, so no signal remains an ownerless warning.
- **SC-006**: Reviewers can determine in one pass which special surface classes require additional tests and which standard native surfaces do not.
- **SC-007**: A low-impact docs-only workflow path remains completable in under 1 minute, a representative guarded review remains completable in under 3 minutes, and neither path requires contributors to answer the same classification question redundantly across workflow surfaces.
## Validation Notes
### Reviewer Workflow Validation
| Scenario | Source artifact | Outcome class | Handling mode | Workflow outcome | Notes |
|---|---|---|---|---|---|
| Low-impact docs-only path | `.specify/templates/checklist-template.md` + `.specify/README.md` | `acceptable-special-case` | `report-only` | `keep` | One `N/A` note stayed sufficient; no fake UI-surface prose was required |
| Fake-native hard signal | `specs/196-hard-filament-nativity-cleanup/spec.md` | `blocker` | `hard-stop-candidate` | `reject-or-split` | Fake-native drift still reaches the strongest guardrail outcome cleanly |
| Shared-family host drift | `specs/197-shared-detail-contract/spec.md` | `strong-warning` | `review-mandatory` | `document-in-feature` | The workflow stops host drift without inventing new categories |
| State-layer confusion | `specs/198-monitoring-page-state/spec.md` + `specs/199-global-context-shell-contract/spec.md` | `strong-warning` | `review-mandatory` | `document-in-feature` | Shell/page/detail ownership now resolves through one fixed question set |
| Legitimate special visualization | `specs/200-filament-surface-rules/spec.md` | `documentation-required-exception` | `exception-required` | `document-in-feature` | Legitimate special cases remain allowed only with bounded exception notes |
- Representative guarded review elapsed time: `02:34`
- Duplicate-question note: the final workflow asks for native/custom, shared-family, and state ownership once in the spec, then reuses that classification in plan, tasks, checklist, and close-out.
### Authoring Workflow Validation
| Scenario | Source artifact | Outcome | Elapsed time | Notes |
|---|---|---|---|---|
| Low-impact docs-only flow | `.specify/templates/checklist-template.md` + `.specify/README.md` | `keep` | `00:48` | Low-impact `N/A` remains fast and does not fabricate runtime obligations |
| Surface-changing authoring flow | `specs/200-filament-surface-rules/spec.md` | `document-in-feature` | `01:51` | Native/custom classification, handling modes, and proof depth stay explicit without adding a second workflow |
### Signal And Test-Trigger Validation
| Drift / surface class | Handling mode | Required proof profile | Close-out expectation |
|---|---|---|---|
| Fake-native hard signal | `hard-stop-candidate` | Special proof only if a bounded exception is claimed | Close-out notes are required only when an exception is still in play |
| Shared-family host drift | `review-mandatory` | `shared-detail-family` | Record host/core boundary and any exception spread control |
| Monitoring or shell state-layer confusion | `review-mandatory` | `monitoring-state-page` or `global-context-shell` | Record state-owner proof and any required smoke |
| Legitimate special visualization | `exception-required` | `exception-coded-surface` | Record bounded exception, preserved standards, and manual smoke |
| Standard native Filament surface | `report-only` | `standard-native-filament` relief | Record ordinary feature coverage only; no bespoke guardrail proof required |
- Standard-native relief rule: standard native Filament work does not need extra bespoke guardrail tests unless it introduces a shared-family contract, shell/page/detail state ownership risk, or a bounded exception.
- Active feature PR close-out entry name: `Guardrail / Exception / Smoke Coverage`
- First-pass automation deferrals remain explicit: report-first signals only, no CI hard-stop, no PR bot, no auto-promotion of review-mandatory cases.

187
specs/201-enforcement-review-guardrails/tasks.md Normal file
View File

@ -0,0 +1,187 @@
# 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.