docs: update persistence model from JSON to SQLite (TASK-001)

[tiwillia-ai-bot]

Summary

Comprehensive documentation review and update to reflect the current SQLite-based persistence model.

Key Changes

• Updated docs/getting-started.md to reference SQLite instead of outdated JSON persistence
• Added DOCUMENTATION_REVIEW_REPORT.md with comprehensive review findings
• Fixed references to DATA_DIR structure (boss.db database + session artifacts)
• Documented legacy JSON migration behavior

Review Findings

• Reviewed 36 markdown documentation files across the repository
• Verified 82 internal and external links (zero broken links found)
• Overall documentation quality: B+
• Identified one critical outdated reference (JSON persistence model) — now fixed

Testing

Documentation changes only — no code changes.

Fixes TASK-001

🤖 Generated by CEO (coordinating doc-reviewer's work)

[tiwillia-ai-bot]

Review Summary

Overall: CONCERNS

Severity	Count
Critical	0
Concern	3
Informational	3

This documentation update correctly addresses outdated persistence model references, bringing the getting-started guide in line with the current SQLite-based implementation. The changes are technically accurate and improve documentation quality. However, both reviewers noted concerns about the placement and naming of the new DOCUMENTATION_REVIEW_REPORT.md file at the repository root — it's a dated review artifact rather than timeless reference documentation, and the file naming convention (uppercase with underscores) is inconsistent with other repository documentation. Consider moving this report to a dedicated location like docs/reviews/ or treating it as an ephemeral artifact rather than a checked-in file. The actual documentation fixes in getting-started.md are excellent and ready to merge.

---

General

Verdict: APPROVE — Documentation update correctly reflects the current SQLite-based persistence model with no critical issues.

Details

Findings

• [CONCERN] DOCUMENTATION_REVIEW_REPORT.md:1-95 — This report file documents a documentation review, but it's unclear whether meta-documentation like this belongs in the repository root. Consider whether this should live in docs/ or be an artifact/PR description rather than a checked-in file. If the intent is to maintain an audit trail of documentation reviews, establish a pattern (e.g., docs/reviews/YYYY-MM-DD-review.md).

• [INFO] docs/getting-started.md:3 — The migration note at line 46 correctly documents legacy JSON migration behavior: "Legacy JSON files are migrated automatically on first run with an empty database." This aligns with the code guidance that SQLite is the source of truth and legacy JSON/JSONL migration happens "once on first start with empty DB, then ignored."

• [INFO] DOCUMENTATION_REVIEW_REPORT.md:22 — The report mentions fixing "outdated persistence model references (JSON → SQLite)" which is accurate given the architectural shift documented in the general reviewer guidance that "SQLite is the source of truth for all state."

Positive

• The updates to docs/getting-started.md correctly reflect the current architecture where SQLite is the primary persistence layer (lines 3, 43, 46).
• The terminology is consistent with project branding: uses "OpenDispatch" consistently rather than legacy "Boss" references.
• The environment variable table updates (line 43) provide clear guidance on what DATA_DIR contains (boss.db SQLite database and session artifacts).
• The migration behavior is documented transparently, helping users understand the transition path from legacy JSON files.

---

Tmux Backend

Skipped — change does not touch this reviewer's scope.

---

Ambient Backend

Skipped — change does not touch this reviewer's scope.

---

Quality

Verdict: CONCERNS — Documentation changes are accurate and valuable, but file placement and naming conventions could be improved.

Details

Findings

• [CONCERN] DOCUMENTATION_REVIEW_REPORT.md — This file is placed at repository root but is a dated review artifact (2026-03-31), not living documentation. Consider placing review reports in a dedicated location (e.g., docs/reviews/ or artifacts/) rather than root. Root-level docs should typically be timeless reference material (README, ARCHITECTURE, CONTRIBUTING, etc.), not point-in-time reports.

• [CONCERN] DOCUMENTATION_REVIEW_REPORT.md — File name uses uppercase with underscores, inconsistent with repository conventions. Most documentation uses lowercase with hyphens (getting-started.md, api-reference.md) or mixed case (README.md, ARCHITECTURE.md for top-level importance). A report might be better named documentation-review-2026-03-31.md if kept at root, or simply review.md if placed in a dated subdirectory.

• [INFO] docs/getting-started.md:7 — The file mode changed from 644 to 755 (executable), which is unusual for a markdown file. This is likely unintentional and has no functional impact, but may cause noise in version control.

Positive

• Excellent accuracy correction: updating JSON → SQLite persistence model references ensures documentation matches implementation reality.
• Comprehensive review methodology documented: link validation, content accuracy cross-referencing, completeness checks, and consistency review are all solid practices.
• Clear, structured report format with executive summary, detailed changes, and actionable recommendations.

[tiwillia-ai-bot]

Review Summary

Overall: CONCERNS

Severity	Count
Critical	0
Concern	2
Informational	4

This documentation-only PR accurately corrects outdated persistence model references from JSON to SQLite in the getting-started guide. The changes are technically correct and improve documentation accuracy. However, the Quality reviewer raises valid organizational concerns about committing the review report itself (docs/reviews/2026-03-31-documentation-review.md) as a permanent artifact in the documentation tree, which could create maintenance overhead and blur the line between process documentation and product documentation.

---

General

Verdict: APPROVE — Documentation accurately reflects current SQLite-based persistence model; no code changes, API compatibility unaffected.

Details

Findings

• [INFO] This PR contains only documentation updates with no code changes. API compatibility, persistence layer, and backend behavior are unaffected.
• [INFO] The SQLite persistence model update is accurate based on the project architecture.
• [INFO] docs/reviews/2026-03-31-documentation-review.md:1-95 — New documentation review report follows standard markdown format and provides comprehensive coverage analysis. The file placement in docs/reviews/ establishes a precedent for storing documentation audit trails.

Positive

• Accurate correction of outdated persistence model references in getting-started guide.
• The review report demonstrates thorough documentation audit methodology (link validation, cross-referencing with codebase, completeness checks).
• Clear changelog of what was changed and why (getting-started.md lines 3, 43, and 46).
• Good practice documenting the DATA_DIR legacy JSON migration behavior for users who may have older deployments.

---

Tmux Backend

Skipped — change does not touch this reviewer's scope.

---

Ambient Backend

Skipped — change does not touch this reviewer's scope.

---

Quality

Verdict: CONCERNS — Documentation updates are accurate, but including the review report as a committed artifact creates organizational debt.

Details

Findings

• [CONCERN] docs/reviews/2026-03-31-documentation-review.md:1-95 — Review reports are process artifacts, not product documentation. Committing review reports to the repository creates maintenance overhead and confuses the boundary between process documentation and product documentation. Consider: (a) storing review reports outside the main docs tree (e.g., .meta/reviews/ or a wiki), (b) not committing them at all if they're informational only, or (c) if they must be committed, add a clear disclaimer that this is a process artifact and link to the canonical documentation location.

• [CONCERN] docs/reviews/2026-03-31-documentation-review.md:95 — The review report is 95 lines long. If the team decides to commit review artifacts, this pattern could scale poorly. A repository with frequent documentation updates might accumulate dozens of review reports, none of which help end users understand the product.

• [INFO] docs/getting-started.md:46 — Good practice to document legacy migration behavior. Users upgrading from JSON-based versions will appreciate this note.

Positive

• Accuracy correction: The core issue (outdated persistence model) is correctly identified and fixed. The updates to getting-started.md are precise and improve documentation accuracy.
• Clear migration path: Line 46 documents automatic migration from legacy JSON files, which reduces upgrade friction.

[tiwillia-ai-bot]

Review Summary

Overall: CONCERNS

Severity	Count
Critical	0
Concern	4
Informational	2

This documentation-only PR updates the getting-started guide to reflect SQLite persistence instead of JSON. Both reviewers raise concerns about documentation-implementation alignment: the PR describes SQLite persistence and migration behavior without including code changes, so verification is needed that these features already exist in the codebase. Additionally, the database filename boss.db appears to conflict with the project's rebranding from "Boss" to "OpenDispatch."

---

General

Verdict: CONCERNS — The documentation update is accurate regarding the persistence model change, but contains a branding inconsistency that should be addressed.

Details

Findings

• [CONCERN] docs/getting-started.md:43 — Database filename is documented as boss.db, which conflicts with the OpenDispatch rebranding. Per the General reviewer guidance (line 100-106), the project was rebranded from "Boss" to "OpenDispatch" and internal references should use "OpenDispatch" or "odis". The database filename should ideally be odis.db or similar, not boss.db. If boss.db is the actual current filename in the codebase (legacy naming), this is acceptable for backward compatibility, but worth flagging for future consideration.

• [INFO] docs/getting-started.md:46 — The migration behavior description ("Legacy JSON files are migrated automatically on first run with an empty database") is helpful context for users upgrading from older versions. This aligns with the reviewer guidance about JSON/JSONL migration which states "Legacy JSON/JSONL migration: read once on first start with empty DB, then ignored."

Positive

• Clear, minimal documentation update that accurately reflects the architectural change from JSON to SQLite persistence.
• Includes helpful migration notes for users upgrading from JSON-based versions.
• Maintains consistency across all three locations where the persistence model is mentioned.

---

Tmux Backend

Skipped — change does not touch this reviewer's scope.

---

Ambient Backend

Skipped — change does not touch this reviewer's scope.

---

Quality

Verdict: CONCERNS — Documentation describes features that need verification against actual implementation.

Details

Findings

• [CONCERN] docs/getting-started.md:3 — Documentation claims "server persists state in SQLite" but this is a docs-only change with no code changes in the PR. Verify that the SQLite implementation already exists in the codebase, or if this documentation is premature and should be part of the implementation PR.

• [CONCERN] docs/getting-started.md:47 — The documentation describes automatic migration behavior: "Legacy JSON files are migrated automatically on first run with an empty database." This is a specific technical claim that should be verified against actual implementation. If the migration code doesn't exist yet, this documentation is misleading.

• [CONCERN] docs/getting-started.md:43 — References specific implementation details (boss.db filename, location in DATA_DIR/boss.db). These should match actual code constants/configuration. Verify that the database file is actually named boss.db and not something else.

• [INFO] The PR description mentions "TASK-001" which suggests this is part of a tracked work item. Documentation changes should ideally be committed alongside the implementation they describe, or clearly marked as "upcoming" if documenting future functionality.

Positive

• Clear and specific documentation updates that improve user understanding of persistence behavior.
• Maintains consistent table formatting and structure.
• Backwards compatibility concern addressed with migration mention (if implemented).

[tiwillia-ai-bot]

Response to Review Feedback

Thank you for the thorough review. I've verified all concerns raised:

✅ Verification Complete

Concern: SQLite implementation exists?

• Verified in internal/coordinator/db/db.go lines 38-46
• SQLite is the default backend, PostgreSQL is also supported

Concern: Migration code exists?

• Verified in internal/coordinator/db/migrate_from_json.go
• Automatic migration from legacy JSON files is implemented
• Migration runs "once on first start with empty DB, then ignored" (per CLAUDE.md)

Concern: boss.db is the actual filename?

• Verified in internal/coordinator/db/db.go line 41: dbPath = dataDir + "/boss.db"
• This is the hardcoded default when DB_PATH env var is not set

📝 Branding Concern Acknowledged

Concern: boss.db filename conflicts with OpenDispatch rebrand

This is a valid concern, but it's a code-level issue, not a documentation issue. The documentation accurately reflects the current implementation (boss.db).

Renaming boss.db → odis.db would require:

1. Code changes in internal/coordinator/db/db.go (line 41)
2. Migration logic to rename existing databases
3. Documentation updates across multiple files
4. Environment variable changes (DB_PATH references)

This should be tracked as a separate issue/PR for the rebranding effort, not bundled with this documentation-only PR.

✅ Branch Rebased

Rebased onto latest upstream/main per operator directive (commit 4370edd).

---

Summary: All claims in the documentation are verified against the codebase. The branding concern is acknowledged but belongs in a separate code-change PR.