Project documentation ownership and navigation¶

Understand what ai-dlc's documentation tools own, what they check, and where specifications, private notes and team pages stay.

ai-dlc organizes references to canonical documents. It does not own a second copy of specifications, a private-note mirror, or a Confluence synchronization engine. The maintained reusable instructions are the project documentation guide, which ships into adopted repositories and owns setup, catalog examples and the upkeep workflow.

The five pillars are navigation questions. What is the system, why were decisions made, what behavior is required, how is it operated, and where are the reference details? Existing project layouts answer them without relocation. OpenSpec owns formal behavior and change artifacts. Repository docs/ owns durable architecture, decisions and operational material. A project index and optional catalog identify canonical paths, ownership, lifecycle and source provenance.

docs check exposes deterministic gaps for review: unknown ownership/review, missing paths, limited local Markdown-link checks, uncatalogued files and exact content duplicates. It does not certify accuracy or automatically consolidate content. Review dates represent an actual review, not filesystem timestamps. OpenSpec remains responsible for its own artifact lifecycle.

Decision records in docs/decisions/ carry the knowledge-note frontmatter of contracts/knowledge-note.schema.json (kind: decision, status, optional checks:). docs check validates that frontmatter when present and reports records without it as information. It fails when an accepted record's body differs from the committed version unless the record moves to superseded.

checks: entries use flightdeck's flightdeck.spec/v1 grammar; ai-dlc checks their shape (unique id, one assert operator, scope and severity values) and never evaluates them. The two-person rule for loosening a check is branch protection and CODEOWNERS, not ai-dlc code. The adopted-project convention is the template's decisions README.

An Obsidian portal is a machine-local Markdown note linking to canonical repository files. It copies no document body and does not mount repository files as editable notes inside the main vault. Personal note operations retain their original vault boundary. Existing project directory links are preserved for manual inspection. No direct Obsidian client qualification is claimed by filesystem tests.

Existing team pages remain authoritative in Confluence; relevant page links and on-demand reads provide context. Later, an explicitly selected repository-authored team guide can have a publication binding with source digest, target identity and expected remote version. Team edits require reconciliation. Reuse the custom Confluence MCP after inspecting its interface. See local and shared knowledge for that workflow.

The formal requirements and repair rationale are in the OpenSpec change.

Evidence and private-workspace extensions¶

The approved documentation program adds Git impact inspection, explicit content-bound dispositions, scoped harness review packets and citation validation. Work records are validated by the work-records check and are not documentation evidence unless explicitly mapped in the catalog. These services coordinate review; they cannot infer semantic accuracy.

A linked Obsidian workspace adds personal navigation and templates while canonical document bodies remain in Git. SDK workflow bundles may carry declared references and exact version applicability, preserving pinned ownership and independent company authority.

The reusable documentation guide linked above owns commands and editorial process. Formal behavior remains in the corresponding OpenSpec changes; verified execution and remaining live qualification are recorded in documentation workflow verification.