flying-jib/agent/DOCUMENTATION_POLICY.md

Documentation Policy

Three trees + agent

Tree	Audience	Freshness rule
living_docs/	Everyone — current truth	Update every significant session
developer_docs/	Contributors	Update with technical changes
user_docs/	End users	Update with user-visible changes
agent/	Humans + AI process	Update when process/rules change

living_docs/

File	When to update
ROADMAP.md	Phase status, acceptance, owners
PROGRESS.md	Append-only each session with real work
CURRENT_STATUS.md	After any “what works” change
ARCHITECTURE_OVERVIEW.md	Design changes
OPEN_QUESTIONS.md	New/resolved questions
CHANGELOG.md	User-visible or notable internal changes

developer_docs/

Update the matching file when you touch that domain (setup, architecture, modules, protocol, build, testing).

user_docs/

• Ship accurate instructions only for implemented features.
• Label incomplete features Planned with phase.
• Never claim multiplayer works until Phase 2 acceptance is met.

ADRs

• Required before architecture/protocol/security merges.
• Status lifecycle: Proposed → Accepted → (Deprecated|Superseded).
• Linking: ROADMAP and ARCHITECTURE should cite ADR numbers.

Same-change rule

Documentation updates belong in the same PR/commit as the code they describe. “Docs follow-up later” is not complete work.

End of session checklist

1. PROGRESS.md entry
2. CURRENT_STATUS.md if reality changed
3. CHANGELOG.md if notable
4. Specialist docs for the area touched
5. ADR if decision changed