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**:
```markdown
<!-- 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**:

```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)

```markdown
<!-- 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)

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

### Web URLs (For Published Docs)

```markdown
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:

```markdown
---
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):

```markdown
---
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)

```bash
# 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