Merge pull request #19 from AmedeoPelliccia/copilot/restrict-subbucket-usage

Restrict subbucket ranges to bucket-specific values in nomenclature validator

Author: AmedeoPelliccia

00_00_CAT_LC01_SPACET_nomenclature-quick-reference_v02.md

@@ -1,9 +1,9 @@
 # Nomenclature Standard Quick Reference
 
-## Pattern
+## Pattern (v2.0 - 8 Fields)
 
 ```
-[ROOT]_[BUCKET]_[TYPE]_[VARIANT]_[DESCRIPTION]_[VERSION].[EXT]
+[ROOT]_[BUCKET]_[TYPE]_[LC_OR_SUBBUCKET]_[VARIANT]_[DESCRIPTION]_[VERSION].[EXT]
 ```
 
 ## Field Rules
@@ -13,19 +13,26 @@
 | ROOT | 2-3 digits | `00`, `24`, `72`, `115`, `116` |
 | BUCKET | 2 digits | `00`, `10`, `20`, `30`, `40`, `50`, `60`, `70`, `80`, `90` |
 | TYPE | 2-8 uppercase | `PLAN`, `FHA`, `REQ`, `STD`, `IDX` |
-| VARIANT | Uppercase + hyphens | `SPACET`, `DRAFT`, `SYS`, `LC02-SPACET` |
+| LC_OR_SUBBUCKET | LC01-LC14 or SB15-SB99 | `LC01`, `LC14`, `SB15`, `SB99` |
+| VARIANT | Uppercase + hyphens | `SPACET`, `DRAFT`, `SYS`, `HW-01` |
 | DESCRIPTION | lowercase-kebab-case | `safety-program`, `propulsion`, `hazard-log` |
 | VERSION | v + 2 digits | `v01`, `v02`, `v10` |
 | EXT | lowercase | `md`, `json`, `xlsx`, `pdf` |
 
 ## Special Rules
 
-### ⚠️ CRITICAL: BUCKET=00 requires LC prefix
+### ⚠️ CRITICAL: Subject Category Rules
 
-If `BUCKET=00`, then `VARIANT` **MUST** start with `LC01` through `LC14`
+**If `BUCKET=00`** → Use **LC** (Lifecycle) category:
+- `LC_OR_SUBBUCKET` **MUST** be `LC01` through `LC14`
+- Example: ✅ `00_00_PLAN_LC02_SPACET_safety-program_v01.md`
+- Invalid: ❌ `00_00_PLAN_SB15_SPACET_safety-program_v01.md`
 
-✅ `00_00_PLAN_LC02-SPACET_safety-program_v01.md`  
-❌ `00_00_PLAN_SPACET_safety-program_v01.md`
+**If `BUCKET≠00`** → Use **SB** (Sub-bucket) category:
+- `LC_OR_SUBBUCKET` **MUST** be `SB15` through `SB99`
+- Example: ✅ `00_70_FHA_SB15_SYS_propulsion_v01.md`
+- Invalid: ❌ `00_70_FHA_SB00_SYS_propulsion_v01.md`
+- Invalid: ❌ `00_70_FHA_LC01_SYS_propulsion_v01.md`
 
 ### Delimiters
 
@@ -34,18 +41,18 @@ If `BUCKET=00`, then `VARIANT` **MUST** start with `LC01` through `LC14`
 
 ## BUCKET Values
 
-| Code | Domain |
-|------|--------|
-| `00` | Lifecycle (requires LC prefix in VARIANT) |
-| `10` | Operations |
-| `20` | Primary Subsystem |
-| `30` | Circularity |
-| `40` | Software |
-| `50` | Structures |
-| `60` | Storages |
-| `70` | Propulsion |
-| `80` | Energy |
-| `90` | Tables/Schemas/Diagrams/Reference |
+| Code | Domain | Allowed Subbuckets |
+|------|--------|-------------------|
+| `00` | Lifecycle | LC01-LC14 |
+| `10` | Operations | SB15-SB19, SB80-SB85 |
+| `20` | Primary Subsystem | SB20-SB29 |
+| `30` | Circularity | SB30-SB39 |
+| `40` | Software | SB40-SB49 |
+| `50` | Structures | SB50-SB59 |
+| `60` | Storages | SB60-SB69 |
+| `70` | Propulsion | SB70-SB79 |
+| `80` | Energy | SB86-SB89 |
+| `90` | Tables/Schemas/Diagrams/Reference | SB90-SB99 |
 
 ## Approved TYPE Codes
 
@@ -76,40 +83,55 @@ python validate_nomenclature.py --check-all
 ### ✅ Valid
 
 ```
-00_00_PLAN_LC02-SPACET_safety-program_v01.md
-00_70_FHA_SYS_propulsion_v01.md
-00_40_REQ_SW_software-safety-reqs_v01.md
-00_20_TRC_SPACET_traceability-matrix_v01.xlsx
-00_90_SCH_GEN_hazard-log-schema_v01.json
-24_40_REQ_SW-01_electrical-power-software_v01.md
+00_00_PLAN_LC02_SPACET_safety-program_v01.md
+00_70_FHA_SB70_SYS_propulsion_v01.md
+00_40_REQ_SB40_SW_software-safety-reqs_v01.md
+00_20_TRC_SB20_SPACET_traceability-matrix_v01.xlsx
+00_90_SCH_SB90_GEN_hazard-log-schema_v01.json
+24_40_REQ_SB40_SW_electrical-power-software_v01.md
+00_10_PLAN_SB15_GEN_operations-plan_v01.md
+00_80_FHA_SB86_SYS_energy-system_v01.md
 ```
 
 ### ❌ Invalid
 
 ```
-00_00_PLAN_SPACET_safety-program_v01.md       # Missing LC prefix
-00-70-FHA-SYS-propulsion-v01.md              # Wrong delimiter
-00_70_FHA_SYS_propulsion_v1.md               # VERSION must be vNN
-00_99_LST_GEN_glossary_v01.md                # Invalid BUCKET
-00_70_FHA_SYS_PropulsionFHA_v01.md           # Uppercase in DESCRIPTION
-00_70_fha_SYS_propulsion_v01.md              # Lowercase TYPE
+00_00_PLAN_SB15_SPACET_safety-program_v01.md  # BUCKET=00 requires LC, not SB
+00_70_FHA_SB00_SYS_propulsion_v01.md          # SB00 not allowed (reserved)
+00_70_FHA_SB40_SYS_propulsion_v01.md          # BUCKET=70 requires SB70-SB79
+00_70_FHA_LC01_SYS_propulsion_v01.md          # BUCKET≠00 requires SB, not LC
+00_40_REQ_SB70_SW_software_v01.md             # BUCKET=40 requires SB40-SB49
+00-70-FHA-SB70-SYS-propulsion-v01.md          # Wrong delimiter
+00_70_FHA_SB70_SYS_propulsion_v1.md           # VERSION must be vNN
+00_99_LST_SB90_GEN_glossary_v01.md            # Invalid BUCKET
+00_70_FHA_SB70_SYS_PropulsionFHA_v01.md       # Uppercase in DESCRIPTION
+00_70_fha_SB70_SYS_propulsion_v01.md          # Lowercase TYPE
 ```
 
 ## Common Mistakes
 
-1. **Missing LC prefix for BUCKET=00**
-   - Fix: Add `LC01` through `LC14` to start of VARIANT
-   - Example: `SPACET` → `LC02-SPACET`
+1. **Wrong subject category for BUCKET=00**: Must use LC01-LC14, not SB
+   - Fix: Use LC_OR_SUBBUCKET field with LC01-LC14
+   - Example: `00_00_PLAN_SB15_SPACET_...` → `00_00_PLAN_LC02_SPACET_...`
 
-2. **Wrong delimiters**
+2. **Using wrong subbucket range for bucket**: Each bucket has specific ranges
+   - Fix: Use the correct subbucket range for your bucket
+   - Example: `00_70_FHA_SB40_SYS_...` → `00_70_FHA_SB70_SYS_...`
+   - Example: `00_40_REQ_SB20_SW_...` → `00_40_REQ_SB40_SW_...`
+
+3. **Using SB00-SB14**: These are reserved and not allowed
+   - Fix: Use bucket-specific ranges starting from SB15
+   - Example: `00_70_FHA_SB00_SYS_...` → `00_70_FHA_SB70_SYS_...`
+
+4. **Wrong delimiters**
    - Fix: Use `_` between fields, `-` inside fields only
    - Example: `00-70-FHA` → `00_70_FHA`
 
-3. **Wrong version format**
+5. **Wrong version format**
    - Fix: Always use 2 digits after `v`
    - Example: `v1` → `v01`
 
-4. **Uppercase in DESCRIPTION**
+6. **Uppercase in DESCRIPTION**
    - Fix: Use lowercase-kebab-case only
    - Example: `SafetyProgram` → `safety-program`
 

00_00_STD_LC01_SPACET_nomenclature-standard_v02.md

@@ -36,7 +36,7 @@ All files must strictly adhere to the **8-field format**:
 | **ROOT**             | ATA Chapter or Project Code           | 2-3 digits                             | `^\d{2,3}$`                  |
 | **BUCKET**           | Domain Classification (OPT-IN + LC)   | 2 digits (enum)                        | `^(00\|10\|20\|30\|40\|50\|60\|70\|80\|90)$` |
 | **TYPE**             | Artifact Type                         | 2–8 uppercase alphanumeric             | `^[A-Z0-9]{2,8}$`            |
-| **LC_OR_SUBBUCKET**  | Lifecycle Stage or Sub-bucket         | LC01-LC14 or SB00-SB99                 | `^(LC(0[1-9]\|1[0-4])\|SB\d{2})$` |
+| **LC_OR_SUBBUCKET**  | Lifecycle Stage or Sub-bucket         | LC01-LC14 or SB15-SB99                 | `^(LC(0[1-9]\|1[0-4])\|SB(1[5-9]\|[2-9]\d))$` |
 | **VARIANT**          | Configuration / Baseline / Item Class | uppercase alphanumeric; hyphen allowed | `^[A-Z0-9]+(?:-[A-Z0-9]+)*$` |
 | **DESCRIPTION**      | Human-readable content label          | lowercase kebab-case                   | `^[a-z0-9]+(?:-[a-z0-9]+)*$` |
 | **VERSION**          | Revision Control                      | `v` + 2 digits                         | `^v\d{2}$`                   |
@@ -94,7 +94,7 @@ The following set is **approved** for v1.0. Extensions require Configuration Man
 
 This mandatory field encodes either:
 - **Lifecycle stage** (LC01-LC14) for `BUCKET=00` files
-- **Sub-bucket** identifier (SB00-SB99) for all other buckets
+- **Sub-bucket** identifier (SB15-SB99) for all other buckets
 
 **Conditional rules (mandatory):**
 
@@ -103,21 +103,36 @@ This mandatory field encodes either:
    ^LC(0[1-9]|1[0-4])$
    ```
    * Valid: `LC01`, `LC02`, ..., `LC14`
-   * Invalid: `SB00`, `LC00`, `LC15`
+   * Invalid: `SB15`, `LC00`, `LC15`
 
-2. **If `BUCKET ≠ 00`** → `LC_OR_SUBBUCKET` **must** match:
+2. **If `BUCKET ≠ 00`** → `LC_OR_SUBBUCKET` **must** match bucket-specific ranges:
    ```regex
-   ^SB\d{2}$
+   ^SB(1[5-9]|[2-9]\d)$
    ```
-   * Valid: `SB00`, `SB01`, ..., `SB99`
-   * Invalid: `LC01`, `SB`, `SBXX`
-   * **Convention**: Use `SB00` if no sub-bucket applies
+   
+   **Bucket-specific subbucket ranges:**
+   
+   | BUCKET | Domain | Allowed Subbuckets |
+   |--------|--------|-------------------|
+   | `10` | Operations | SB15-SB19, SB80-SB85 |
+   | `20` | Primary Subsystem | SB20-SB29 |
+   | `30` | Circularity | SB30-SB39 |
+   | `40` | Software | SB40-SB49 |
+   | `50` | Structures | SB50-SB59 |
+   | `60` | Storages | SB60-SB69 |
+   | `70` | Propulsion | SB70-SB79 |
+   | `80` | Energy | SB86-SB89 |
+   | `90` | Tables/Schemas/Diagrams | SB90-SB99 |
+   
+   * Invalid: `LC01`, `SB00`, `SB01`, ..., `SB14`, `SB`, `SBXX`
+   * Invalid: Subbuckets outside the allowed range for the specific BUCKET
+   * **Convention**: SB00-SB14 are reserved; each bucket has designated ranges
 
 **Sub-bucket mapping:**
-* `SB00` = No sub-bucket / Not applicable
-* `SB01` = Maps to directory sub-bucket `*-01_*` (e.g., `00-20-01_*`)
-* `SB02` = Maps to directory sub-bucket `*-02_*`
-* etc.
+* Each BUCKET uses designated subbucket ranges aligned with the domain
+* Ranges are enforced to maintain clear separation between buckets
+* Note: SB00-SB14 are reserved and not available for use
+
 
 ### 4.5 `[VARIANT]` (Configuration / Baseline)
 
@@ -138,7 +153,7 @@ Hyphenated variants are allowed: `SYS-01`, `SW-PLAT-A`.
 
 * Must be lowercase kebab-case.
 * Must not duplicate semantic content already encoded in `TYPE` or `BUCKET`.
-  * Example: avoid `..._FHA_SYS_propulsion-fha_...` → use `..._FHA_SB00_SYS_propulsion_...`
+  * Example: avoid `..._FHA_SYS_propulsion-fha_...` → use `..._FHA_SB15_SYS_propulsion_...`
 
 ### 4.7 `[VERSION]`
 
@@ -154,7 +169,7 @@ Hyphenated variants are allowed: `SYS-01`, `SW-PLAT-A`.
 This regex validates the general filename structure for v2.0:
 
 ```regex
-^(?<root>\d{2})_(?<bucket>00|10|20|30|40|50|60|70|80|90)_(?<type>[A-Z0-9]{2,8})_(?<stage>(LC(0[1-9]|1[0-4])|SB\d{2}))_(?<variant>[A-Z0-9]+(?:-[A-Z0-9]+)*)_(?<desc>[a-z0-9]+(?:-[a-z0-9]+)*)_(?<ver>v\d{2})\.(?<ext>[a-z0-9]{1,6})$
+^(?<root>\d{2})_(?<bucket>00|10|20|30|40|50|60|70|80|90)_(?<type>[A-Z0-9]{2,8})_(?<stage>(LC(0[1-9]|1[0-4])|SB(1[5-9]|[2-9]\d)))_(?<variant>[A-Z0-9]+(?:-[A-Z0-9]+)*)_(?<desc>[a-z0-9]+(?:-[a-z0-9]+)*)_(?<ver>v\d{2})\.(?<ext>[a-z0-9]{1,6})$
 ```
 
 ### 5.2 Conditional Rules (Mandatory)
@@ -166,10 +181,11 @@ CI shall additionally enforce:
   ^LC(0[1-9]|1[0-4])$
   ```
 
-* **If `bucket != "00"`** then `stage` matches:
+* **If `bucket != "00"`** then `stage` matches bucket-specific ranges:
   ```regex
-  ^SB\d{2}$
+  ^SB(1[5-9]|[2-9]\d)$
   ```
+  And falls within the bucket's designated range (see section 4.4)
 
 ---
 
@@ -179,17 +195,21 @@ CI shall additionally enforce:
 
 * Lifecycle (LC) plan:
   * `00_00_PLAN_LC02_SPACET_safety-program_v02.md`
-* Propulsion FHA (domain bucket with no sub-bucket):
-  * `00_70_FHA_SB00_SYS_propulsion_v02.md`
+* Propulsion FHA (domain bucket with sub-bucket):
+  * `00_70_FHA_SB70_SYS_propulsion_v02.md`
 * Software safety requirements:
-  * `00_40_REQ_SB00_SW_software-safety-reqs_v02.md`
+  * `00_40_REQ_SB40_SW_software-safety-reqs_v02.md`
 * Traceability matrix workbook:
-  * `00_20_TRC_SPACET_traceability-matrix_v01.xlsx`
+  * `00_20_TRC_SB20_SPACET_traceability-matrix_v01.xlsx`
 * Reference schema:
-  * `00_90_SCH_GEN_hazard-log-schema_v01.json`
+  * `00_90_SCH_SB90_GEN_hazard-log-schema_v01.json`
+* Operations plan:
+  * `00_10_PLAN_SB15_GEN_operations-plan_v01.md`
+* Energy system FHA:
+  * `00_80_FHA_SB86_SYS_energy-system_v01.md`
 * Extended ATA code (3-digit ROOT):
   * `115_00_PLAN_LC01_SPACET_supply-chain-plan_v01.md`
-  * `116_70_FHA_SB00_SYS_facility-systems_v01.md`
+  * `116_70_FHA_SB70_SYS_facility-systems_v01.md`
 
 ### 6.2 Invalid examples
 

validate_nomenclature.py

@@ -44,7 +44,7 @@ class NomenclatureValidator:
         r'^(?P<root>\d{2,3})_'
         r'(?P<bucket>00|10|20|30|40|50|60|70|80|90)_'
         r'(?P<type>[A-Z0-9]{2,8})_'
-        r'(?P<stage>(LC(0[1-9]|1[0-4])|SB\d{2}))_'
+        r'(?P<stage>(LC(0[1-9]|1[0-4])|SB(1[5-9]|[2-9]\d)))_'
         r'(?P<variant>[A-Z0-9]+(?:-[A-Z0-9]+)*)_'
         r'(?P<desc>[a-z0-9]+(?:-[a-z0-9]+)*)_'
         r'(?P<ver>v\d{2})'
@@ -54,15 +54,28 @@ class NomenclatureValidator:
     # LC stage pattern (LC01-LC14)
     LC_PATTERN = re.compile(r'^LC(0[1-9]|1[0-4])$')
 
-    # SB stage pattern (SB00-SB99)
-    SB_PATTERN = re.compile(r'^SB\d{2}$')
+    # SB stage pattern (SB15-SB99)
+    SB_PATTERN = re.compile(r'^SB(1[5-9]|[2-9]\d)$')
 
     # VERSION format pattern
     VERSION_PATTERN = re.compile(r'^v\d{2}$')
 
     # Allowed buckets
     ALLOWED_BUCKETS = {'00', '10', '20', '30', '40', '50', '60', '70', '80', '90'}
 
+    # Bucket-specific subbucket ranges
+    BUCKET_SUBBUCKET_RANGES = {
+        '10': [(15, 19), (80, 85)],  # Operations: SB15-SB19 + SB80-SB85
+        '20': [(20, 29)],             # Primary Subsystem: SB20-SB29
+        '30': [(30, 39)],             # Circularity: SB30-SB39
+        '40': [(40, 49)],             # Software: SB40-SB49
+        '50': [(50, 59)],             # Structures: SB50-SB59
+        '60': [(60, 69)],             # Storages: SB60-SB69
+        '70': [(70, 79)],             # Propulsion: SB70-SB79
+        '80': [(86, 89)],             # Energy: SB86-SB89
+        '90': [(90, 99)],             # Tables/Schemas/Diagrams/Reference: SB90-SB99
+    }
+    
     # Approved TYPE vocabulary
     APPROVED_TYPES = {
         # Planning / Control
@@ -178,8 +191,31 @@ def validate_filename(self, filename: str) -> ValidationResult:
             # BUCKET≠00 requires SB stage
             if not self.SB_PATTERN.match(stage):
                 errors.append(
-                    f"BUCKET={bucket} requires LC_OR_SUBBUCKET to be SB00-SB99, got '{stage}'"
+                    f"BUCKET={bucket} requires LC_OR_SUBBUCKET to be SB format, got '{stage}'"
                 )
+            else:
+                # Validate bucket-specific subbucket range
+                if bucket in self.BUCKET_SUBBUCKET_RANGES:
+                    try:
+                        # Extract numeric part from stage (e.g., "SB15" -> 15)
+                        sb_num = int(stage[2:])
+                        ranges = self.BUCKET_SUBBUCKET_RANGES[bucket]
+                        
+                        # Check if subbucket number is in any of the allowed ranges for this bucket
+                        in_range = any(start <= sb_num <= end for start, end in ranges)
+                        
+                        if not in_range:
+                            # Format ranges for error message
+                            range_strs = [f"SB{start:02d}-SB{end:02d}" for start, end in ranges]
+                            allowed = " or ".join(range_strs)
+                            errors.append(
+                                f"BUCKET={bucket} requires LC_OR_SUBBUCKET to be {allowed}, got '{stage}'"
+                            )
+                    except (ValueError, IndexError):
+                        # This should not happen if SB_PATTERN matched, but handle defensively
+                        errors.append(
+                            f"Invalid subbucket format '{stage}' for BUCKET={bucket}"
+                        )
 
         # Check for redundancy in DESCRIPTION
         desc_lower = desc.lower()