docs: Address distributed systems review feedback in ceads-design#1
Merged
Conversation
High-priority fixes: - Fix ID generation algorithm: correct base36 encoding, increase entropy to 64 bits - Fix sync algorithm: use content hash for conflict detection (not version comparison) to prevent silent data loss when two agents edit independently - Move last_sync from synced meta.json to local state.json to eliminate hotspot - Add canonical JSON serialization requirement for consistent content hashes - Add deterministic tie-breaker (updated_at + entity ID) for LWW conflicts Documentation improvements: - Clarify union strategy limitations (add-only, removals don't propagate) - Document deletion semantics (soft-delete recommended, hard-delete discouraged) - Clarify schema-agnostic sync vs schema-aware merge distinction - Add jitter/backoff to sync retry documentation - Document atomic write mechanics (tmp file + rename pattern) - Add extensions namespace in BaseEntity for third-party data - Document heartbeat churn concerns and mitigation strategies - Clarify parent_id vs sequence authority for hierarchical issues These changes address critical correctness issues identified in the distributed systems review while preserving the design's simplicity goals.
Second round of distributed systems review incorporating clean, actionable improvements: - Upgrade attic schema to capture base/ours/theirs/chosen for better conflict debugging - Make messages immutable (edits become new messages with supersedes reference) - Change EntityType from closed enum to regex pattern for true extensibility - Add 3-way set merge algorithm for labels (supports additions AND removals) - Document hidden worktree as recommended sync implementation (resolves Open Question 1) - Add nanoid as recommended ID generation library alternative - Use Windows-safe ISO 8601 basic format for attic filenames (no colons) Deferred items documented in ceads-design-review-plan.md: - Full Git 3-way merge driver architecture - Claims as first-class entities - Declarative merge rules file
Comprehensive external ID system inspired by Beads: - External IDs use project prefix from config.yaml (e.g., "proj-a1b") - Internal IDs remain fixed 10-char hashes (e.g., "is-a1b2c3d4e5") - Short IDs are randomly generated, not derived from internal IDs - Adaptive length based on issue count using birthday paradox math: - 0-100 issues: 3 chars - 101-600: 4 chars - 601-3,500: 5 chars - etc. - Mapping stored in .ceads-sync/short_ids.json (append-only, synced) - Project prefix is display-only concern, can be renamed anytime Includes collision probability tables, TypeScript algorithms, and distributed collision handling strategy.
Following the same pattern as entity storage for consistency and to
avoid merge conflicts:
- Store in .ceads-sync/short_ids/{short_id}.json
- Each file contains: {"internal_id": "is-..."}
- Filename IS the short ID (self-describing)
- No merge conflicts (different short IDs = different files)
- Last-write-wins on collision (loser regenerates short ID on sync)
- No attic needed - current state is always authoritative
Benefits over single-file approach:
- No contention on every issue create
- Natural LWW conflict resolution via Git
- Simple recovery: scan for internal ID, regenerate if missing
jlevy
pushed a commit
that referenced
this pull request
Jan 17, 2026
Merged Beads vs tbd comparison into main review document. Now includes: Bugs (6 total): - #1: Exit codes return 0 on errors (CRITICAL) - #2: Dependency direction semantics confusing - #3: Search outputs message with --quiet - #4: Doctor warns on empty issues dir - #5: Import changes ID prefix - #6: Errors not JSON with --json flag Enhancements (20 total): - Critical (3): exit codes, npm publish, git version check - High (5): dep semantics, error JSON, tests, docs, import prefix - Medium (7): brief flag, templates, query DSL, batch ops, etc. - Low (5): history, GitHub sync, plugins, index, auto-links Key finding: tbd's single session protocol is better than Beads' 5 conditional protocols. Keep it simple.
gbasin
added a commit
to gbasin/tbd
that referenced
this pull request
Feb 12, 2026
Design decisions applied: - Remove AI spec review from v1 (harness expects finished spec) - Move human_review gate to Phase 2 (after decomposition) - Agents receive entire frozen spec (no section extraction) - Cycle detection in buildDependencyGraph() — fail fast - Deadlock detection in scheduler (blocked-bead deadlock) - Process group killing via detached: true + kill(-pid) - Resume re-reads harness.yml for operational config changes - Trust agent push (no post-completion verification) New sections: - Example Agent Prompt (complete prompt template) - Known Limitations (soft isolation, spec tampering, Unix-only, no cost controls, LWW) - Deadlock Detection (cycle + blocked-bead scenarios) Fixes: - Pipeline diagram: removed AI review box, fixed "dedicated" → "fresh" worktree - Agent Pool Model: "dedicated worktree" → "fresh ephemeral worktree" - JudgeResult.newBeads: added 'feature' type - Config YAML: human_review under phases.decompose with correct comment - Defaults: added guidelines, completion checks, acceptance model - Open Questions: resolved jlevy#1 (entire spec) and jlevy#6 (port algorithm) - Code Organization: added lib/graph.ts - Process Lifecycle: spawn with detached:true, SIGTERM targets process groups - Testing: added cycle detection, deadlock, process group, resume config tests - Future Work: added preview-acceptance, spec review phase, Windows, hash verify Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
jlevy
pushed a commit
that referenced
this pull request
May 7, 2026
The user pointed out the new Design Principles in the docs-config plan should be cross-referenced and consolidated with the existing tbd-design principles. Three changes: 1. tbd-design.md §1.5 (Design Principles) extended from 6 to 10: - #1 (Simplicity first) extended to spell out "simple things simple, complex things possible". - #3 (Git for sync) extended with the reproducible-from-config contract. - #7 added: Auth is always out-of-band — tbd never holds credentials. - #8 added: Hard cuts on format versions with reliable migration — already practiced for f02→f03; making it an explicit principle. - #9 added: Spec ↔ implementation synchrony via tests. - #10 added: Layered architecture, separable artifacts. These four new principles emerged from the docs-config redesign work but apply tbd-wide. 2. tbd-design.md §1.4 Design Goals: added goal #8 (extensible knowledge subsystem), which links forward to the plan-spec and the docref/ docmap design docs as the authoritative location for that subsystem's design. 3. plan-spec Design Principles intro: now explicitly notes that P1, P5, P6, P7, P8, P9 are restatements/elaborations of tbd-design §1.5 principles, while P2, P3, P4 are docs/config-specific and have no direct system-wide analog. Each restated principle gets an inline "(extends tbd-design §1.5 #N)" cross-reference. tbd-design.md is declared authoritative for system-wide values. This consolidates principles in one foundational location (tbd-design.md) while keeping the docs-config plan readable on its own. https://claude.ai/code/session_01PhbYdWX7DUBpUBVuUesVuP
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
High-priority fixes:
to prevent silent data loss when two agents edit independently
Documentation improvements:
These changes address critical correctness issues identified in the distributed
systems review while preserving the design's simplicity goals.