tractatus/docs/DOCUMENTATION_OWNERSHIP.md

Documentation Ownership and Single Source of Truth

Date: November 2, 2025 Version: 1.0.0 Status: Authoritative

Purpose

This document defines documentation ownership across the multi-project ecosystem to prevent drift, duplication, and inconsistency. It establishes the single source of truth principle for all documentation.

Core Principle

Single Source of Truth: Each concept, specification, or guide has exactly ONE authoritative location. All other references LINK to the source, never duplicate.

Project Roles

Tractatus (Framework Authority)

Repository: /home/theflow/projects/tractatus Role: Source of truth for ALL framework concepts, schemas, and governance principles

Owns:

• Framework philosophy and principles
• Governance rule schemas (all versions: v1.0, v2.0, v3.0)
• Authorization system architecture
• PreToolUse hook specifications
• Meta-governance concepts
• Framework implementation guides
• Security classification system

Example Authoritative Documents:

• docs/SCHEMA_V3_SPECIFICATION.md - Rule schema specification
• docs/GOVERNANCE_AUTHORIZATION_SYSTEM_PLAN.md - Authorization architecture
• docs/HUB_AND_SPOKE_ARCHITECTURE.md - Multi-project pattern
• docs/FRAMEWORK_PHILOSOPHY.md - Tractatus philosophical foundation
• .claude/instruction-history.json - Reference implementation (50 rules)

Family-History (Implementation Example)

Repository: /home/theflow/projects/family-history Role: Reference implementation demonstrating framework usage in production SaaS

Owns:

• Family-history specific implementation details
• Multi-tenant architecture patterns
• Production deployment procedures
• Session handoff methodology
• Application-specific governance rules

References from Tractatus:

• Schema v3.0 specification → link to tractatus
• Authorization system design → link to tractatus
• Framework concepts → link to tractatus

Example Authoritative Documents:

• CLAUDE.md - Family-history quick reference
• docs/session-handoffs/ - Session methodology (may be promoted to tractatus)
• .claude/instruction-history.json - Implementation example (42 rules)

Platform-Admin (Ecosystem Coordinator)

Repository: /home/theflow/projects/platform-admin Role: Aggregator and cross-project coordinator, NOT authoritative source

Owns:

• Hub-specific operational procedures
• Cross-project analytics and reporting
• Project registry metadata
• Meta-governance rules (hub-specific only)

References Everything:

• Framework concepts → link to tractatus
• Project implementations → link to source projects
• Schemas and specs → link to tractatus

Example Documents:

• docs/project-profiles/ - Profiles LINK to source docs, minimal duplication
• README.md - Hub overview with links
• .claude/instruction-history.json - Meta-governance only (8 rules)

Documentation Ownership Map

Topic	Authority	Location	Other Projects
Framework Concepts	Tractatus	docs/	Link only
Schema v1.0, v2.0, v3.0	Tractatus	docs/SCHEMA_V3_SPECIFICATION.md	Link only
Authorization System	Tractatus	docs/GOVERNANCE_AUTHORIZATION_SYSTEM_PLAN.md	Link only
Hub-and-Spoke Pattern	Tractatus	docs/HUB_AND_SPOKE_ARCHITECTURE.md	Link only
PreToolUse Hooks	Tractatus	docs/PRETOOLUSE_HOOKS.md	Link only
Security Classifications	Tractatus	docs/SECURITY_CLASSIFICATION.md	Link only
Governance Philosophy	Tractatus	docs/FRAMEWORK_PHILOSOPHY.md	Link only
Implementation Examples
Multi-tenant Patterns	Family-history	docs/MULTI_TENANT_ARCHITECTURE.md	Reference as example
Session Handoffs	Family-history	docs/session-handoffs/	May promote to tractatus
Deployment Procedures	Family-history	scripts/deploy-*.sh, CLAUDE.md	Implementation-specific
Port Management	Shared	~/PORT_ALLOCATION_REGISTRY.md	All projects reference
Project-Specific
Family-history Operations	Family-history	CLAUDE.md	N/A
Platform-admin Operations	Platform-admin	README.md	N/A
Project Profiles	Platform-admin	docs/project-profiles/	MUST link to sources

Reference vs. Duplication Rules

When to Link (Preferred)

✅ ALWAYS link when:

• Describing framework concepts
• Referencing schemas or specifications
• Explaining governance principles
• Citing authorization procedures
• Documenting meta-governance

Example:

<!-- In family-history/docs/GOVERNANCE_IMPLEMENTATION.md -->

This project uses Schema v3.0 for governance rules.

See authoritative specification:
[Schema v3.0](file:///home/theflow/projects/tractatus/docs/SCHEMA_V3_SPECIFICATION.md)

Or in platform-admin: `../../../tractatus/docs/SCHEMA_V3_SPECIFICATION.md`

When to Duplicate (Rare)

⚠️ Only duplicate when:

• Quick reference needed (with clear "See [source] for details" link)
• Project-specific adaptation of general concept
• Offline/standalone documentation required

Requirements if duplicating:

1. Clearly mark as "Summary - See [source] for authoritative version"
2. Include link to source of truth
3. Add metadata: source: tractatus/docs/FILE.md, last_synced: 2025-11-02
4. Keep to absolute minimum (prefer links)

Update Procedures

Updating Authoritative Documents

For Tractatus (Framework Authority):

1. Before editing: Verify this is the source of truth
2. Make changes: Edit authoritative document in tractatus
3. Update version: Increment version number in document
4. Update metadata: Note what changed and when
5. Notify dependents: Check which projects reference this doc
6. Verify links: Ensure all links still work
7. Governance log: Record change in GovernanceAuditLog if applicable

For Project-Specific Docs:

1. Edit in owning project: Never edit in referring project
2. Update references: If structure changes, update links
3. Session handoff: Document significant changes

Adding New Documentation

Decision Tree:

1. Is this a framework concept? → Tractatus owns it
2. Is this implementation-specific? → Source project owns it
3. Is this cross-project coordination? → Platform-admin coordinates (with links)
4. Unsure? → Default to Tractatus for governance topics, source project otherwise

Migrating Existing Documentation

Current State (as of 2025-11-02):

• ❌ Schema v3.0 spec in family-history (should be in tractatus)
• ❌ Authorization plan in family-history (should be in tractatus)
• ❌ Framework rules audit in family-history (should be in tractatus)
• ✅ Project profiles in platform-admin (correct, but should link more)

Migration Plan:

Phase 1: Move to Tractatus (Priority: HIGH)

1. Move family-history/docs/SCHEMA_V3_SPECIFICATION.md → tractatus/docs/
2. Move family-history/docs/GOVERNANCE_AUTHORIZATION_SYSTEM_PLAN.md → tractatus/docs/
3. Move family-history/docs/FRAMEWORK_RULES_AUDIT.md → tractatus/docs/
4. Create hub-and-spoke doc: tractatus/docs/HUB_AND_SPOKE_ARCHITECTURE.md

Phase 2: Update References (Priority: HIGH)

1. Update family-history docs to link to tractatus
2. Update platform-admin project profiles to link instead of duplicate
3. Add source metadata to any remaining duplications

Phase 3: Verify (Priority: MEDIUM)

1. Check all links work
2. Verify no broken references
3. Update documentation indices

Governance Rules

inst_documentation_single_source

To be added to tractatus instruction-history.json:

{
  "id": "inst_documentation_single_source",
  "title": "Documentation Single Source of Truth Required",
  "category": "DOCUMENTATION",
  "quadrant": "STRATEGIC",
  "persistence": "HIGH",
  "description": "All documentation MUST follow single source of truth principle. Link to authoritative source instead of duplicating.",
  "context": "Multi-project ecosystem with tractatus, family-history, platform-admin, and future projects. Documentation drift causes confusion and maintenance burden.",
  "rationale": "Single source prevents inconsistency, reduces maintenance, ensures everyone has latest information, and makes updates easier.",
  "trigger": "Creating or updating any documentation that references framework concepts, schemas, or cross-project patterns.",
  "action": "Consult DOCUMENTATION_OWNERSHIP.md to determine authority. Link to source instead of duplicating. If duplicating is absolutely necessary, include source link and last_synced metadata.",
  "validation": "Documentation review checks for unauthorized duplication. Links verified to point to authoritative sources.",
  "evidence": "Pull request reviews, documentation audits, link verification scripts."
}

Link Format Standards

Relative Links (Preferred for Git)

<!-- From family-history to tractatus -->
See [Schema v3.0](../../tractatus/docs/SCHEMA_V3_SPECIFICATION.md)

<!-- From platform-admin to tractatus -->
See [Authorization System](../../tractatus/docs/GOVERNANCE_AUTHORIZATION_SYSTEM_PLAN.md)

<!-- Within same project -->
See [Session Handoffs](docs/session-handoffs/README.md)

Absolute Paths (For Scripts/Tools)

See: /home/theflow/projects/tractatus/docs/SCHEMA_V3_SPECIFICATION.md

Web URLs (For Published Docs)

See: https://docs.tractatus-framework.org/schema/v3.0

Documentation Index

Tractatus (Source of Truth)

Framework Core:

• docs/FRAMEWORK_PHILOSOPHY.md - Wittgenstein foundation
• docs/SCHEMA_V3_SPECIFICATION.md - Rule schema (authoritative)
• docs/GOVERNANCE_AUTHORIZATION_SYSTEM_PLAN.md - Authorization architecture
• docs/PRETOOLUSE_HOOKS.md - Hook specification
• docs/SECURITY_CLASSIFICATION.md - Security levels (PUBLIC → SECRET)

Patterns:

• docs/HUB_AND_SPOKE_ARCHITECTURE.md - Multi-project pattern
• docs/META_GOVERNANCE.md - Recursive governance

Implementation:

• .claude/instruction-history.json - Reference implementation (50 rules)
• docs/IMPLEMENTATION_GUIDE.md - How to adopt framework

Family-History (Implementation Example)

Quick Reference:

• CLAUDE.md - Operations quick reference
• docs/session-handoffs/ - Session methodology

Architecture:

• docs/MULTI_TENANT_ARCHITECTURE.md - Multi-tenancy patterns

Implementation:

• .claude/instruction-history.json - Production example (42 rules)

Platform-Admin (Aggregator)

Coordination:

• README.md - Hub overview
• docs/project-profiles/ - Project summaries (with links to sources)

Hub-Specific:

• .claude/instruction-history.json - Meta-governance (8 rules)

Metadata Standards

All documentation should include:

---
title: Document Title
authority: tractatus | family-history | platform-admin
version: 1.0.0
last_updated: 2025-11-02
status: authoritative | reference | deprecated
references:
  - ../path/to/source.md
  - https://external-source.com
---

For duplicated content (rare):

---
source: /home/theflow/projects/tractatus/docs/SOURCE.md
last_synced: 2025-11-02
sync_status: up-to-date | out-of-date | deprecated
warning: This is a COPY. See source for authoritative version.
---

Verification Procedures

Manual Review

Before committing documentation:

1. Check ownership: Is this the authoritative location?
2. Verify links: Do all references point to correct sources?
3. Check duplication: Is this content duplicated elsewhere?
4. Update metadata: Version, date, references up-to-date?

Automated Checks (Future)

# Planned: Documentation audit script
./scripts/audit-documentation.sh

# Would check:
# - Broken links
# - Unauthorized duplication
# - Missing metadata
# - Out-of-sync copies

Migration Checklist

• Move Schema v3.0 spec to tractatus
• Move Authorization plan to tractatus
• Move Framework rules audit to tractatus
• Create hub-and-spoke architecture doc in tractatus
• Update family-history references to link to tractatus
• Update platform-admin project profiles to link not duplicate
• Add source metadata to remaining duplications
• Verify all links work
• Add inst_documentation_single_source to tractatus
• Create documentation audit script
• Update README files with documentation structure

Conflict Resolution

If unsure which project should own documentation:

1. Framework concepts → Tractatus (default)
2. Implementation details → Source project
3. Cross-project coordination → Platform-admin (but link to sources)

If documentation already exists in multiple places:

1. Identify which is most complete and up-to-date
2. Designate that as authoritative
3. Move to correct project if needed
4. Update all others to link to authoritative version
5. Add deprecation notices to old locations

Success Metrics

Short Term (This Week)

• All framework docs in tractatus
• All projects link to tractatus for framework concepts
• No unauthorized duplication of framework specs

Medium Term (This Month)

• Documentation ownership clear for all topics
• All links verified and working
• Metadata standards implemented

Long Term (3 Months)

• Automated link verification
• Zero documentation drift detected
• New projects follow ownership model from day 1

Conclusion

Single source documentation maintenance is critical for ecosystem health. By clearly defining ownership and enforcing the "link, don't duplicate" principle, we ensure:

• ✅ Consistency across projects
• ✅ Easier maintenance (update once, not 3 times)
• ✅ Clear authority (no ambiguity about which doc is correct)
• ✅ Reduced cognitive load (developers know where to look)

Next Steps: Execute migration plan to move framework docs to tractatus and update all references.

---

Authority: Tractatus Framework Maintained by: John G Stroh Review Schedule: Quarterly or when adding new projects