ADR-014: Multi-Root Documentation Sources

[rehsack]

Summary

• Adds ADR-014 (Proposed): Multi-root documentation support with workspace/reference access modes
• Enables cross-project documentation contexts without duplicating content or risking unintended modifications
• Motivated by real-world scenarios: industrial product portfolios, Yocto layer stacks, spec/template co-development

Key Decisions

• Explicit key=value CLI format (--reference name=...,type=...,path=...) — cross-platform safe (Windows, System i/z, URIs)
• Two access modes: workspace (read-write) and reference (read-only, stable by definition)
• Namespace separation: each root gets a name, section paths are prefixed
• Document roles: documentation (core content) and project-meta (README, LLM.md, etc.)
• Template type as opaque metadata: dacli annotates (type=arc42), does not interpret
• spec key: points LLM to framework guidance (path or MCP server ID) for unfamiliar templates
• New tool get_namespaces: entry point for LLM orientation across roots

Discussion Points

This is a Proposed ADR — seeking feedback on the approach before implementation. Key areas:

1. Is the key=value CLI format the right trade-off between explicitness and usability?
2. Does the role classification (documentation vs. project-meta) cover real-world needs?
3. Should .dacli.json per root be JSON or TOML? What fields?
4. Integration path with ADR-007: Persistent SQLite Index for CLI Performance and Fuzzy Search #185 (SQLite Index) and RAG via sqlite-vec: Vector search for documentation Q&A #265 (RAG)

Test plan

• Review ADR for completeness and consistency
• Validate against additional real-world scenarios
• Discuss integration with existing architecture (ADR-001, ADR-002, ADR-007)

🤖 Generated with Claude Code