---
_version: '1'
uuid: 3f8b9d42-7e1c-4a93-9f6d-2e4a5b8c1d3f
created: 2025-10-26T00:00:00Z
tags:
- configuration
- directory-structure
- namespaces
parents:
- uuid: 19cf66b3-6a6a-49d0-8438-f102c761ec27
fingerprint: placeholder_fingerprint_will_be_updated
hrid: USR-008
---
# SYS-016 Directory Structure Modes
## Statement
The tool shall support two directory structure modes controlled by the `subfolders_are_namespaces` configuration option: filename-based mode (default) where the full HRID is encoded in the filename and folders are purely organizational, and path-based mode where subfolders encode the namespace and the filename contains only KIND-ID.
## Rationale
Different projects have different organizational needs:
1. **Filename-based mode** provides maximum flexibility - files can be organized in arbitrary folder structures without affecting their HRIDs, making it ideal for teams that reorganize frequently or use folders for non-semantic purposes (e.g., organizing by team, feature, or priority).
2. **Path-based mode** creates a tighter coupling between folder structure and namespaces, resulting in cleaner filenames and enforced consistency between directory hierarchy and requirement organization, ideal for projects with stable hierarchical component structures.
Supporting both modes allows teams to choose the approach that best fits their workflow while maintaining backward compatibility.
## Scope
The configuration must let administrators choose the storage convention that matches their repository culture without sacrificing traceability. Switching the mode should feel deliberate, guided, and reversible, with clear affordances for inferring namespaces and preserving HRIDs.
User prompts, configuration touchpoints, and migration guidance are maintained in [SPC-004](./SPC-004.md).
## Verification
- Filename-based mode continues to load existing repositories without change.
- Opting into path-based mode allows namespace inference from folder structure while preserving canonical HRIDs.
- Misconfigured paths or filenames produce actionable error messaging rather than silent corruption.