doc: spec-driver

Author: davidlee

.claude/settings.local.json

@@ -1,3 +1,4 @@
+
 /pi-mono
 /result
 .spec-driver/run/*

.gitignore

@@ -39,7 +39,7 @@ phases: []
 ## 1. Summary & Context
 
 - **Technical Spec(s)**: SPEC-117 (decisions), SPEC-126 (policies), SPEC-127 (standards)
-- **Change Drivers**: Code quality audit identified 8 reimplementations of sequential ID generation, 3 identical `parse_date()` copies, 3 identical title extraction blocks, 3 inlined atomic write patterns, 5 duplicated code-fence regex patterns, 2 identical `_matches_pattern` functions.
+- **Change Drivers**: Code quality audit identified 8 reimplementations of sequential ID generation, 3 identical `parse_date()` copies, 3 identical title extraction blocks, 3 inlined atomic write patterns, 6 duplicated code-fence regex patterns, 2 identical `_matches_pattern` functions.
 - **Governance**: POL-001 (maximise code reuse), ADR-009 (standard registry convention)
 
 ## 2. Motivation
@@ -52,15 +52,15 @@ Multiple utility functions are copy-pasted across domain modules with zero or tr
 | Sequential ID generation | 8 (`_next_identifier`, `determine_next_identifier`, `generate_next_adr_id`, `generate_next_policy_id`, `generate_next_standard_id`, `_next_ledger_id`, `next_identifier`, `CardRegistry.next_id`) | Same algorithm, different prefix strings |
 | Title extraction from H1 | 3 (decisions, policies, standards registries)                                                                                                                                                     | Same logic, different prefix             |
 | Atomic file write        | 3 (`review_io.py` extracted, `state_io.py` + `handoff_io.py` inlined)                                                                                                                             | Identical pattern                        |
-| Code-fence block regex   | 5 (delta.py, verification.py, relationships.py, plan.py ×2)                                                                                                                                       | Same regex template, different marker    |
+| Code-fence block regex   | 6 (delta.py, relationships.py, verification.py, plan.py ×3)                                                                                                                                       | Same regex template, different marker    |
 | `_matches_pattern`       | 2 (common.py, find.py)                                                                                                                                                                            | Byte-for-byte identical                  |
 | `create_title_slug`      | 2 (policies, standards creation)                                                                                                                                                                  | 1-line passthrough to `slugify()`        |
 
 ## 3. Scope & Objectives
 
 - **Primary Outcomes**:
   - New `core/dates.py`: shared `parse_date(value) -> date | None`
-  - New `core/ids.py`: shared `next_sequential_id(directory, prefix, pattern) -> str`
+  - New `core/ids.py`: shared `next_sequential_id(names, prefix, separator="-") -> str`
   - Extend `core/spec_utils.py`: shared `extract_title_from_content(content, prefix) -> str`
   - New `core/io.py`: shared `atomic_write(path, content)` (promoted from `review_io._atomic_write`)
   - Extend `blocks/yaml_utils.py`: `make_block_pattern(marker) -> re.Pattern`