# 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
