# Spec Review Guidance (Automation Placeholder)

This folder contains placeholders for future GitHub Actions or bot-based checks that can validate spec quality before merge.

## Current Scope
- Validate required documents exist under `features/<feature>/` for completed specs.
- Enforce stable ID format for requirements and scenarios.
- Check for required cross-links between PRD, Architecture, Contracts, Scenarios, and Decisions.
- Validate shared reference links when feature specs reference shared personas, invariants, security requirements, observability requirements, or compatibility guidance.

## Suggested Checks (to automate later)

### 1) File Check
Required per feature:
- `PRD.md`

Optional per feature:
- `Scenarios.md`

### 2) ID Format Check
- Optional `JIRA` field in PRD frontmatter with explicit ticket-like identifiers only (for example `FRM-1234`, `PORT-567`)
- `FR-001`, `FR-002`, ... (exact 3-digit)
- `INV-001`, `INV-002`, ...
- `SCN-001`, `SCN-002`, ...

### 3) Cross-Link Check
- Every scenario should include requirement IDs (`FR-###` or `INV-###`).
- Scenario validation references should use plain ID lists such as `Validates: FR-001, INV-002` rather than linked documentation-graph formatting.
- Shared references should prefer direct Markdown links when a feature cites shared requirement IDs such as `INV-GLOBAL-*`, `SEC-*`, `OBS-*`, or `COMP-*`.
- When a shared requirement link is present, both the target file and the heading anchor should resolve correctly.
- Raw shared IDs are acceptable in prose only when the context is not meant to link directly to the shared source entry.

### 4) Human + AI Readability Check
- Heading structure should be stable and machine-parseable.
- Section order should remain predictable across feature specs.
- No ambiguous placeholders like `TBD` for required traceability fields before merge.
- Scenario validation metadata should stay concise and consistent across the repo.
- Shared-link formatting should remain readable to humans and deterministic for parsers, for example `[OBS-001](../../shared/observability-requirements.md#obs-001-health-and-progress-metrics)`.

## Implementation Placeholder
- Add a GitHub Action workflow under `.github/workflows/spec-review.yml`.
- Add markdown parser and ID extraction scripts under `automation/`.
- Add shared-link validation that checks both relative path existence and heading-anchor normalization for linked shared references.
- Export a JSON artifact with validation pass/fail and actionable remediation hints.