---
_version: '1'
uuid: b295fffe-25a7-43c0-8c90-f41cfc61b0bd
created: 2025-10-27T12:15:00Z
parents:
- uuid: 3f8b9d42-7e1c-4a93-9f6d-2e4a5b8c1d3f
fingerprint: 4fdb93c19c79ebbdad75e3090aa5f5fc46145812cfe6921579b750b838049c21
hrid: SYS-016
---
# SPC-004 Directory Structure Modes Specification
## Purpose
Help maintainers confidently choose and manage the directory mode that fits their organisation—without breaking existing HRIDs—through clear configuration touchpoints, status feedback, and migration guidance.
## Configuration UX
- `req config show` displays the current mode as `subfolders_are_namespaces: false (filename mode)` or `true (path mode)`.
- Changing the setting through `req config set subfolders_are_namespaces true` yields:
```
Directory mode: path-based
• Filenames inside namespace folders should contain KIND-ID (e.g., USR/003.md).
• You will need to manually reorganize existing files to match the new structure.
```
- When toggling back to filename mode, surface a reminder: `Namespaces will no longer be inferred from folders.` plus a link to docs (`See docs/src/requirements/SPC-004.md#migration-guide`).
## Creation & Editing Flow
- When in path-based mode and the user creates a requirement without a namespace folder, prompt:
```
Destination folder 'requirements/USR/' not found.
Create it now? (Y/n)
```
Accept uppercase `Y` as default. Declining falls back to filename mode behaviour for that operation.
- Saving a requirement checks the inferred HRID and, if mismatched, prints:
`Mismatch: path implies namespace 'system/auth', but HRID is 'payment-USR-002'.`
Provide two remedies: `1) Rename the file`, `2) Update YAML hrid`. Exit `64`.
## Migration Guide
- When switching between filename-based and path-based modes, existing files must be manually reorganized.
- Use `req diagnose paths` to identify files that need to be moved.
- Documentation snippet (this spec) includes a checklist:
1. Commit a clean working tree.
2. Enable the desired directory mode with `req config set subfolders_are_namespaces true/false`.
3. Run `req diagnose paths` to identify files that need reorganization.
4. Manually move files to their expected locations and review diff.
## Feedback & Diagnostics
- `req status` (when enhanced later) should flag inconsistent files as a warning: `⚠️ 3 files violate directory mode expectations (run 'req diagnose paths').`
- `req diagnose paths` summarises issues per folder and suggests fixes, prioritising actionable language over raw errors.
- Error messages mention both the problematic path and the expected pattern (e.g., `Expected 'KIND-ID.md', found 'somefile.txt'`).
## Accessibility Considerations
- All instructions use sentence case, short paragraphs, and 80-column wraps.
- Prompts mirror the `[Y/n]` convention so screen readers announce defaults properly.
- When terminal colour is disabled, swap coloured bullets for ASCII equivalents (`*`).