Beads persistence, workflow drift fixes, reality OSS baseline

.beads/.gitignore

@@ -1,44 +1,51 @@
-# SQLite databases
-*.db
-*.db?*
-*.db-journal
-*.db-wal
-*.db-shm
+# Dolt database (managed by Dolt, not git)
+dolt/
+dolt-access.lock
 
-# Daemon runtime files
-daemon.lock
-daemon.log
-daemon.pid
+# Runtime files
 bd.sock
+bd.sock.startlock
 sync-state.json
 last-touched
 
 # Local version tracking (prevents upgrade notification spam after git ops)
 .local_version
 
-# Legacy database files
-db.sqlite
-bd.db
-
 # Worktree redirect file (contains relative path to main repo's .beads/)
 # Must not be committed as paths would be wrong in other clones
 redirect
 
-# Merge artifacts (temporary files from 3-way merge)
-beads.base.jsonl
-beads.base.meta.json
-beads.left.jsonl
-beads.left.meta.json
-beads.right.jsonl
-beads.right.meta.json
-
 # Sync state (local-only, per-machine)
 # These files are machine-specific and should not be shared across clones
 .sync.lock
-sync_base.jsonl
+export-state/
+
+# Ephemeral store (SQLite - wisps/molecules, intentionally not versioned)
+ephemeral.sqlite3
+ephemeral.sqlite3-journal
+ephemeral.sqlite3-wal
+ephemeral.sqlite3-shm
 
-# NOTE: Do NOT add negation patterns (e.g., !issues.jsonl) here.
-# They would override fork protection in .git/info/exclude, allowing
-# contributors to accidentally commit upstream issue databases.
-# The JSONL files (issues.jsonl, interactions.jsonl) and config files
-# are tracked by git by default since no pattern above ignores them.
+# Dolt server management (auto-started by bd)
+dolt-server.pid
+dolt-server.log
+dolt-server.lock
+dolt-server.port
+dolt-server.activity
+dolt-monitor.pid
+
+# Backup data (auto-exported JSONL, local-only)
+backup/
+
+# Legacy files (from pre-Dolt versions)
+*.db
+*.db?*
+*.db-journal
+*.db-wal
+*.db-shm
+db.sqlite
+bd.db
+# NOTE: Do NOT add negation patterns here.
+# They would override fork protection in .git/info/exclude.
+# Config files (metadata.json, config.yaml) are tracked by git by default
+# since no pattern above ignores them.

.beads/config.yaml

@@ -37,12 +37,14 @@
 # Debounce interval for auto-flush (can also use BEADS_FLUSH_DEBOUNCE)
 # flush-debounce: "5s"
 
-# Git branch for beads commits (bd sync will commit to this branch)
-# IMPORTANT: Set this for team projects so all clones use the same sync branch.
+# Git branch for exported beads snapshots in this repo.
+# IMPORTANT: Set this for team projects so all clones use the same branch default.
 # This setting persists across clones (unlike database config which is gitignored).
 # Can also use BEADS_SYNC_BRANCH env var for local override.
-# If not set, bd sync will require you to run 'bd config set sync.branch <branch>'.
-# sync-branch: "beads-sync"
+# For beads >=0.59, repo workflows use ./scripts/beads_import_only.sh and
+# ./scripts/beads_export.sh instead of `bd sync`.
+# Public sdp work targets main by default.
+sync-branch: "main"
 
 # Multi-repo configuration (experimental - bd-307)
 # Allows hydrating from multiple repositories and routing writes to the correct JSONL

.beads/hooks/post-checkout

@@ -0,0 +1,9 @@
+#!/usr/bin/env sh
+# --- BEGIN BEADS INTEGRATION v0.59.0 ---
+# This section is managed by beads. Do not remove these markers.
+if command -v bd >/dev/null 2>&1; then
+  export BD_GIT_HOOK=1
+  bd hooks run post-checkout "$@"
+  _bd_exit=$?; if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
+fi
+# --- END BEADS INTEGRATION v0.59.0 ---

.beads/hooks/post-merge

@@ -0,0 +1,9 @@
+#!/usr/bin/env sh
+# --- BEGIN BEADS INTEGRATION v0.59.0 ---
+# This section is managed by beads. Do not remove these markers.
+if command -v bd >/dev/null 2>&1; then
+  export BD_GIT_HOOK=1
+  bd hooks run post-merge "$@"
+  _bd_exit=$?; if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
+fi
+# --- END BEADS INTEGRATION v0.59.0 ---

.beads/hooks/pre-commit

@@ -0,0 +1,9 @@
+#!/usr/bin/env sh
+# --- BEGIN BEADS INTEGRATION v0.59.0 ---
+# This section is managed by beads. Do not remove these markers.
+if command -v bd >/dev/null 2>&1; then
+  export BD_GIT_HOOK=1
+  bd hooks run pre-commit "$@"
+  _bd_exit=$?; if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
+fi
+# --- END BEADS INTEGRATION v0.59.0 ---

.beads/hooks/pre-push

@@ -0,0 +1,9 @@
+#!/usr/bin/env sh
+# --- BEGIN BEADS INTEGRATION v0.59.0 ---
+# This section is managed by beads. Do not remove these markers.
+if command -v bd >/dev/null 2>&1; then
+  export BD_GIT_HOOK=1
+  bd hooks run pre-push "$@"
+  _bd_exit=$?; if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
+fi
+# --- END BEADS INTEGRATION v0.59.0 ---

.beads/hooks/prepare-commit-msg

@@ -0,0 +1,9 @@
+#!/usr/bin/env sh
+# --- BEGIN BEADS INTEGRATION v0.59.0 ---
+# This section is managed by beads. Do not remove these markers.
+if command -v bd >/dev/null 2>&1; then
+  export BD_GIT_HOOK=1
+  bd hooks run prepare-commit-msg "$@"
+  _bd_exit=$?; if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
+fi
+# --- END BEADS INTEGRATION v0.59.0 ---

.beads/issues.jsonl

@@ -20,3 +20,5 @@
 {"id":"sdp-y7dg","title":"Verifier: fix context propagation + defer-in-loop","description":"verifier.go:76 creates context.Background() ignoring parent. defer cancel() in loop leaks. See design doc B6","status":"open","priority":1,"issue_type":"bug","owner":"a_v_zhukov@outlook.com","created_at":"2026-02-25T13:38:16.734468+03:00","created_by":"Andrei","updated_at":"2026-02-25T13:38:16.734468+03:00","labels":["P1","audit","go-quality"]}
 {"id":"sdp-ycsn","title":"Config: configurable timeouts with env override","description":"Add timeouts section to config.yml schema. Add SDP_TIMEOUT_* env override pattern. See design doc B12","status":"open","priority":2,"issue_type":"task","owner":"a_v_zhukov@outlook.com","created_at":"2026-02-25T13:39:10.712876+03:00","created_by":"Andrei","updated_at":"2026-02-25T13:39:10.712876+03:00","labels":["P2","audit","go-quality"]}
 {"id":"sdp-yout","title":"Evidence: TestEmit_EventuallyWrites uses polling - potential flakiness","status":"open","priority":3,"issue_type":"bug","owner":"a_v_zhukov@outlook.com","created_at":"2026-02-25T14:34:07.239423+03:00","created_by":"Andrei","updated_at":"2026-02-25T14:34:07.239423+03:00","labels":["qa","review-finding","round-1","sdp-repo"]}
+{"id":"sdp-30a","title":"Validate multi-service and multi-language decomposition against real fixtures","description":"Create real mixed-topology fixtures to verify SDP decomposes features across multiple services and languages with explicit boundaries, service ownership, and per-surface build/test commands instead of collapsing everything into one generic workstream.","status":"open","priority":1,"issue_type":"task","owner":"a_v_zhukov@outlook.com","created_at":"2026-03-13T10:27:14+03:00","created_by":"Andrei","updated_at":"2026-03-13T10:27:34+03:00"}
+{"id":"sdp-903","title":"Add e2e coverage for long feature descriptions and admin intake","description":"Add end-to-end fixtures for multi-paragraph feature requests so /feature -> @idea -> @design stays on the skill path, preserves the full description, and asks product questions for admin/backoffice surfaces before workstream creation.","status":"open","priority":1,"issue_type":"task","owner":"a_v_zhukov@outlook.com","created_at":"2026-03-13T10:27:14+03:00","created_by":"Andrei","updated_at":"2026-03-13T10:27:34+03:00"}

.beads/metadata.json

@@ -1,4 +1,7 @@
 {
-  "database": "beads.db",
-  "jsonl_export": "issues.jsonl"
+  "database": "dolt",
+  "backend": "dolt",
+  "dolt_mode": "server",
+  "dolt_database": "beads",
+  "project_id": "0863fa69-bf25-45fb-9f7d-3b43fb0c1a14"
 }

.gitignore

@@ -61,8 +61,8 @@ archive/
 .sdp/checkpoints/
 !.sdp/evidence/
 !.sdp/checkpoints/
-.sdp/log/events.jsonl
-sdp-plugin/.sdp/log/events.jsonl
+.sdp/log/
+sdp-plugin/.sdp/log/
 **/events.jsonl
 
 # Build output
@@ -87,6 +87,7 @@ sdp-plugin/cmd/sdp/sdp
 # Beads daemon and temp files
 *.startlock
 daemon-error
+sdp-plugin/cmd/sdp/.beads/
 sdp-plugin/.beads/*.db
 sdp-plugin/.beads/*.db-shm
 sdp-plugin/.beads/*.db-wal
@@ -97,3 +98,7 @@ sdp-plugin/**/.sdp/
 # Demo project (created by vhs demo.tape)
 demo-beads-viz/
 demo-project/
+
+# Dolt database files (added by bd init)
+.dolt/
+*.db

AGENTS.md

@@ -9,7 +9,9 @@ bd ready              # Find available work
 bd show <id>          # View issue details
 bd update <id> --status in_progress  # Claim work
 bd close <id>         # Complete work
-bd sync               # Sync with git
+./scripts/beads_import_only.sh  # Rebuild local beads DB from tracked JSONL
+./scripts/beads_export.sh       # Export beads DB back to .beads/issues.jsonl
+bd doctor             # Diagnose local beads/Dolt health
 ```
 
 ## Quality Gates
@@ -36,6 +38,118 @@ For Go changes, follow the canonical `@go-modern` skill in `prompts/skills/go-mo
 
 **MANDATORY WORKFLOW:**
 
+1. **File issues for remaining work** - Create issues for anything that needs follow-up
+2. **Run quality gates** (if code changed) - Tests, linters, builds
+3. **Update issue status** - Close finished work, update in-progress items
+4. **PUSH TO REMOTE** - This is MANDATORY:
+   ```bash
+   git pull --rebase
+   ./scripts/beads_import_only.sh   # if .beads/issues.jsonl changed after pull
+   ./scripts/beads_export.sh        # if you changed beads in this session
+   git push
+   git status  # MUST show "up to date with origin"
+   ```
+5. **Clean up** - Clear stashes, prune remote branches
+6. **Verify** - All changes committed AND pushed
+7. **Hand off** - Provide context for next session
+
+**CRITICAL RULES:**
+- Work is NOT complete until `git push` succeeds
+- NEVER stop before pushing - that leaves work stranded locally
+- NEVER say "ready to push when you are" - YOU must push
+- If push fails, resolve and retry until it succeeds
+
+<!-- BEGIN BEADS INTEGRATION -->
+## Issue Tracking with bd (beads)
+
+**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
+
+### Why bd?
+
+- Dependency-aware: Track blockers and relationships between issues
+- Git-friendly: Dolt-powered version control with native sync
+- Agent-optimized: JSON output, ready work detection, discovered-from links
+- Prevents duplicate tracking systems and confusion
+
+### Quick Start
+
+**Check for ready work:**
+
+```bash
+bd ready --json
+```
+
+**Create new issues:**
+
+```bash
+bd create "Issue title" --description="Detailed context" -t bug|feature|task -p 0-4 --json
+bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --json
+```
+
+**Claim and update:**
+
+```bash
+bd update <id> --claim --json
+bd update bd-42 --priority 1 --json
+```
+
+**Complete work:**
+
+```bash
+bd close bd-42 --reason "Completed" --json
+```
+
+### Issue Types
+
+- `bug` - Something broken
+- `feature` - New functionality
+- `task` - Work item (tests, docs, refactoring)
+- `epic` - Large feature with subtasks
+- `chore` - Maintenance (dependencies, tooling)
+
+### Priorities
+
+- `0` - Critical (security, data loss, broken builds)
+- `1` - High (major features, important bugs)
+- `2` - Medium (default, nice-to-have)
+- `3` - Low (polish, optimization)
+- `4` - Backlog (future ideas)
+
+### Workflow for AI Agents
+
+1. **Check ready work**: `bd ready` shows unblocked issues
+2. **Claim your task atomically**: `bd update <id> --claim`
+3. **Work on it**: Implement, test, document
+4. **Discover new work?** Create linked issue:
+   - `bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:<parent-id>`
+5. **Complete**: `bd close <id> --reason "Done"`
+
+### Auto-Sync
+
+bd automatically syncs via Dolt:
+
+- Each write auto-commits to Dolt history
+- Use `bd dolt push`/`bd dolt pull` for remote sync
+- No manual export/import needed!
+
+### Important Rules
+
+- ✅ Use bd for ALL task tracking
+- ✅ Always use `--json` flag for programmatic use
+- ✅ Link discovered work with `discovered-from` dependencies
+- ✅ Check `bd ready` before asking "what should I work on?"
+- ❌ Do NOT create markdown TODO lists
+- ❌ Do NOT use external issue trackers
+- ❌ Do NOT duplicate tracking systems
+
+For more details, see README.md and docs/QUICKSTART.md.
+
+## Landing the Plane (Session Completion)
+
+**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
+
+**MANDATORY WORKFLOW:**
+
 1. **File issues for remaining work** - Create issues for anything that needs follow-up
 2. **Run quality gates** (if code changed) - Tests, linters, builds
 3. **Update issue status** - Close finished work, update in-progress items
@@ -55,3 +169,5 @@ For Go changes, follow the canonical `@go-modern` skill in `prompts/skills/go-mo
 - NEVER stop before pushing - that leaves work stranded locally
 - NEVER say "ready to push when you are" - YOU must push
 - If push fails, resolve and retry until it succeeds
+
+<!-- END BEADS INTEGRATION -->

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to the Spec-Driven Protocol (SDP).
 
+## [Unreleased]
+
+### Reality OSS Publication Polish
+
+- Published open `reality` schemas under `schema/reality/`
+- Added `sdp reality validate` for emitted OSS artifact checks
+- Aligned CLI/help/completions with the actual OSS `reality` baseline
+- Added public `reality` spec docs and a focused OSS reference/checklist
+
 ## [0.9.8] - 2026-02-26
 
 ### Skills Sync, Beads Integration

CLAUDE.md

@@ -8,7 +8,7 @@ Quick reference for using SDP CLI v0.9.8 with Claude Code.
 
 ```bash
 @vision "AI-powered task manager"    # Strategic planning
-@reality --quick                     # Codebase analysis
+@reality --quick                     # Local codebase baseline
 @feature "Add user authentication"   # Plan feature
 @build 00-001-01                     # Execute workstream
 @review <feature-id>                 # Quality check
@@ -67,15 +67,15 @@ New project?
 | Level | Orchestrator | Purpose | Output |
 |-------|-------------|---------|--------|
 | **Strategic** | @vision (7 agents) | Product planning | VISION, PRD, ROADMAP |
-| **Analysis** | @reality (8 agents) | Codebase analysis | Reality report |
+| **Analysis** | @reality (single-repo baseline) | Local codebase analysis | Reality artifacts |
 | **Feature** | @feature (roadmap pre-check + @discovery + @idea + @ux + @design) | Requirements + WS | Workstreams |
 | **Execution** | @oneshot (@build) | Parallel execution | Implemented code |
 
 ### When to Use Each Level
 
 **@vision** — New project, major pivot, quarterly strategic review
 
-**@reality** — New to project, before @feature, track tech debt, quarterly review
+**@reality** — New to project, before @feature, establish a local baseline, track tech debt, quarterly review
 
 **@feature** — Feature idea but no workstreams, need interactive planning (full discovery flow)
 
@@ -96,7 +96,7 @@ New project?
 | Skill | Purpose | Phase |
 |-------|---------|-------|
 | `@vision` | Strategic product planning (7 expert agents) | Strategic |
-| `@reality` | Codebase analysis (8 expert agents) | Analysis |
+| `@reality` | Local single-repo baseline scan | Analysis |
 | `@feature` | Planning orchestrator (roadmap pre-check + discovery + idea + ux + design) | Planning |
 | `@discovery` | Product discovery gate (roadmap check, research loop) | Planning |
 | `@idea` | Requirements gathering (AskUserQuestion) | Planning |
@@ -152,6 +152,7 @@ New project?
 
 # 2. Codebase analysis
 @reality --quick
+sdp reality emit-oss --quick
 
 # 3. Feature planning (per feature)
 @feature "User can reset password via email"
@@ -411,7 +412,8 @@ Run test coverage tool with verbose output to identify gaps
 4. **PUSH TO REMOTE:**
    ```bash
    git pull --rebase
-   bd sync
+   ./scripts/beads_import_only.sh   # if .beads/issues.jsonl changed after pull
+   ./scripts/beads_export.sh        # if you changed beads in this session
    git push
    git status  # MUST show "up to date with origin"
    ```