# `.specify/` (Tooling)

This folder contains **SpecKit tooling** (templates, scripts, constitution, etc.).

## Important

- **Do not** create new feature specs in `.specify/spec.md`, `.specify/plan.md`, `.specify/tasks.md`.
- Active feature specs live under `specs/<NNN>-<slug>/`:
  - `spec.md`
  - `plan.md`
  - `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 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 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 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.