BOHICA-LABS / BOHICA-LABS/vsdd-factory
enhancement(architecture): canonical subsystem-registry.yaml to unify name/shard/class-name mappings
- Dominant language
- Rust
- Stars
- 2
- Forks
- 1
- Avg merge
- 6h 43m
- Merged PRs (30d)
- 29
Description
## Summary
Many lint scripts and review tasks need to map between three representations of the same subsystem:
1. Human name: `GameManager`, `SaveManager`, `PuzzleSystem`, etc.
2. Shard filename: `ss-NN-game-manager.md`, `ss-NN-save-system.md`, `ss-NN-puzzle-system.md`.
3. Source class name: `game_manager.gd`, `save_manager.gd`, etc.
Today, every lint that needs this mapping builds its own ad-hoc translation table. Examples from the ftc-blue cycle:
- `lint-di-namespace-owner.sh` had to derive shard from name to check `l2-invariants:` frontmatter.
- `lint-di-subsystem-frontmatter-coverage.sh` (pass-9 addition) had to do the same.
- Manual review tasks (consistency-validator, adversary) keep cross-referencing these by hand.
This:
- Wastes time per-lint reimplementing the same translation.
- Introduces inconsistency bugs (e.g., `ZoneManager` vs `Zone Manager` vs `zone_manager` — which form is canonical?).
- Makes the spec corpus harder for humans to navigate, since the mapping is everywhere implicit.
## Proposed change
Add a canonical subsystem registry at `.factory/specs/architecture/subsystem-registry.yaml` (or similar canonical path) with structure:
```yaml
version: "1.0"
subsystems:
- id: SS-01
name: CharacterController
shard: architecture/subsystems/ss-01-character-controller.md
source_class: character_controller.gd
capabilities: [CAP-001, CAP-002]
aliases: [Character Controller, character-controller]
- id: SS-08
name: SaveManager
shard: architecture/subsystems/ss-08-save-system.md
source_class: save_manager.gd
capabilities: [CAP-008]
aliases: [Save Manager, save-manager, save-system]
# ...
```
Then:
- Lints can `yq` the registry instead of building ad-hoc mappings.
- A new lint can enforce that every shard's frontmatter `subsystem-id:` matches its registry entry.
- The registry doubles as documentation for new contributors.
- Cross-doc consistency (e.g., ARCH-INDEX §3 vs module-decomposition.md vs shard frontmatter) becomes machine-checkable.
## Applies to
- New file: `.factory/specs/architecture/subsystem-registry.yaml`
- `templates/subsystem-registry-template.yaml`
- All lints that map subsystem name ↔ shard: update to consume the registry
- New lint: `lint-subsystem-registry-coverage.sh` (every shard appears in registry; every registry entry has a shard file)
## Acceptance criteria
- [ ] Registry file format defined and templated
- [ ] At least 3 existing lints refactored to consume the registry
- [ ] Registry coverage lint catches mismatches
- [ ] Documentation explains the registry's role and update workflow
## Found during
ftc-blue Phase 1d adversarial cycle (2026-06-23, vsdd-factory@1.0.0-rc.21). Specifically the pass-8 + pass-9 devops lint additions, which each had to build their own subsystem mapping.
## Notes
This is part of a broader "central registries reduce drift" pattern. See also Issue #4 (decision-registry pre-flight) and Issue #5 (lint coverage debt ledger).
Contributor guide
Assessment
This issue has not been assessed yet.