# SPEC ID Normalization Policy
**Revision:** 2025-10-25
**Owners:** Test Optimization WG / Specs WG

## Purpose
Provide a consistent workflow for renaming or consolidating SPEC IDs across documentation and automated tests during Phase7c and later phases.

## Scope
- Applies to SPEC IDs referenced in tests (@pytest.mark.spec(...)), meta documents (specs/meta/*.md), requirements mappings, and roadmap reports.
- Covers both incremental renames (e.g., adding suffixes) and wholesale consolidation of obsolete IDs.

## Goals
1. Prevent drift between documentation and automated test markers.
2. Ensure historical traceability when SPEC IDs change.
3. Minimize churn during large-scale cleanups (Phase7c/Phase8).

---

## Normalization Workflow

1. **Inventory & Proposal**
   - Run python scripts/generate_spec_marker_report.py（内部で pytest --collect-only -q | rg "SPEC-" を実行）または python scripts/spec_marker_inventory.py（予定）で対象 SPEC の出現箇所を一覧化。
   - Draft rename plan in 
eports/spec_id_changes/YYYYMMDD_<short>.md including old ID, new ID, rationale, impacted files count.

2. **Approval & Scheduling**
   - Share the proposal during weekly Phase7 sync; obtain sign-off from Specs WG.
   - Assign Wave（例: Wave1: top 10 IDs, Wave2: long tail）と担当者・締切を 
eports/phase7c_spec_consolidation_plan.md に追記。

3. **Document Updates**
   - Update primary spec documents (specs/archive/*.md or live specs) to reflect the new ID.
   - Update meta maps (specs/meta/*_TEST_MAP.md), SPEC_INTEGRATION_REPORT.md, and REQ_SPEC_MAPPING_MATRIX.md simultaneously。
   - Append change log entry (date, author, summary) to affected meta files.

4. **Test Updates**
   - Use targeted search/replace (
g "SPEC-OLD" -l) and update pytest markers。
   - For shared tests (ラッパーモジュール), ensure imports and comment guidance remain valid。
   - Run pytest --collect-only -q -k "SPEC-NEW" to confirm new ID is discoverable。

5. **Validation & Logging**
   - Execute focused suite: pytest -k "SPEC-NEW" または対象フォルダのユニットテスト。
   - Capture output to 
eports/logs/spec_id_updates/<date>_<spec>.txt。
   - Update 
eports/Phase7_Improvements_Roadmap.md metrics (remaining counts etc.)。

6. **Communication**
   - Post summary in weekly digest (
eports/weekly/), including before/after counts。
   - Notify DevEx team if tooling updates (lint rules, CI filters) are required。

---

## Naming Conventions
- Prefer descriptive suffixes (e.g., SPEC-EPISODE-006-COMPLETED_EPISODE_LIFECYCLE)。
- Use SCREAMING_SNAKE_CASE after the numeric segment; avoid spaces and diacritics。
- Reserve top-level numeric ranges:
  - SPEC-EPISODE-*: Episode lifecycle & completion。
  - SPEC-PLOT-*: Plot/foreshadowing features。
  - SPEC-QUALITY-*: Quality pipelines & audits。
  - SPEC-STAGED-*: Staged workflows。
  - SPEC-INFRASTRUCTURE: Infrastructure glue (consider sub-suffices during Phase8)。

---

## Checklist (per SPEC ID)
- [ ] Proposal reviewed & approved。
- [ ] Specs/documents updated。
- [ ] Tests updated (pytest --collect-only / -k)。
- [ ] Logs archived。
- [ ] Roadmap metrics updated。
- [ ] Change summary shared with stakeholders。

---

## Appendix
- Template: 
eports/spec_id_changes/TEMPLATE_SPEC_ID_CHANGE.md
- Related docs: specs/meta/SPEC-EPISODE-006_TEST_MAP.md, specs/meta/SPEC_INTEGRATION_REPORT.md, 
eports/Phase7_Improvements_Roadmap.md。
- Tooling backlog: Add CLI helper for marker renames (JIRA: QA-482)。

