forge-workflow 0.0.8 → 0.0.10

package/docs/TOOLCHAIN.md

@@ -31,190 +31,175 @@ Complete reference for all tools integrated with the Forge workflow.
 
 ---
 
-## Beads - Git-Backed Issue Tracking
+## Shell Model
 
-**Package**: `@beads/bd`
-**Repository**: [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
+Forge commands and repo scripts run under the shell shown below:
+
+| Platform | Shell used by Forge commands and scripts |
+| --- | --- |
+| Windows | Git Bash for helper-backed Forge stage flows |
+| macOS/Linux | Default login shell |
+
+Windows gotchas:
+
+- Forge runtime health enforces Git Bash on Windows for helper-backed flows and reports `Git Bash is required on Windows for helper-backed flows.` when it is missing.
+- Native PowerShell is still used by some bootstrap paths, such as Beads installation, but it is not the enforced shell for helper-backed stage execution.
+- WSL may be useful for adjacent development tasks, but it is not the Windows shell policy currently enforced by Forge runtime checks.
+
+---
+
+## Beads - Dolt-Backed Issue Tracking
+
+**Package**: `@beads/bd`  
+**Repository**: [github.com/steveyegge/beads](https://github.com/steveyegge/beads)  
 **Purpose**: Distributed issue tracking designed for AI coding agents
 
-### Why Beads?
+### Current Forge Target
 
-- **Persists across sessions** - Issues survive context clearing, compaction, new chats
-- **Git-backed** - Version controlled, mergeable, team-shareable
-- **Dependency tracking** - Know what blocks what
-- **Ready detection** - `bd ready` finds unblocked work automatically
-- **AI-optimized** - JSON output, semantic compaction, audit trails
+- Forge now targets the stable Beads `v1.0.0` release for repo setup and CI.
+- Routine team sync still goes through `forge sync`.
+- Use `bd` directly for Beads features Forge does not wrap yet, such as `bd init`, `bd comments`, `bd dep`, `bd blocked`, `bd backup`, and `bd dolt *`.
 
-### Installation
+### Install or Update Beads
 
-**Auto-installation** (Recommended):
+**Recommended**:
 ```bash
 bunx forge setup
-# Prompts: "Install Beads? (y/n)"
-# Automatically installs and initializes
-# On Windows: uses PowerShell installer (npm @beads/bd has an EPERM bug on Windows)
+bd --version
 ```
 
-**Manual installation**:
+**Manual install**:
 ```bash
-# macOS / Linux (global)
-bun add -g @beads/bd
-bd init
-
-# macOS / Linux (local)
-bun add -d @beads/bd
-bunx bd init
-
-# Windows (global) — use PowerShell installer, NOT npm/bun add -g
+# Windows
 irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
-bd init
+bd --version
 
-# Or with bunx (macOS/Linux, no install needed)
-bunx @beads/bd init
+# CI / pinned Linux install
+BD_VERSION="1.0.0"
+BD_URL="https://github.com/steveyegge/beads/releases/download/v${BD_VERSION}/beads_${BD_VERSION}_linux_amd64.tar.gz"
+mkdir -p "$HOME/.local/bin"
+curl -fsSL "$BD_URL" | tar -xz -C "$HOME/.local/bin" bd
+chmod +x "$HOME/.local/bin/bd"
 ```
 
-> **Windows note**: The `npm install -g @beads/bd` postinstall script uses `Expand-Archive`, which triggers an EPERM file-locking error on Windows (issue #1031, closed "not planned"). Use the PowerShell installer above instead.
+Verify the installed CLI before using it:
+
+```bash
+bd --version
+bd doctor
+```
 
-### File Structure
+### Supported Repo Layout
 
-After `bd init`, creates `.beads/` directory:
+Forge treats `.beads/` as the repo-local Beads home directory. The layout in this repository currently includes:
 
-```
+```text
 .beads/
-├── issues.jsonl      # Issue data (git-tracked, one JSON per line)
-├── beads.db          # SQLite cache (git-ignored, fast queries)
-├── metadata.json     # Database metadata
-├── config.yaml       # User configuration
-├── interactions.jsonl # Agent audit log
-└── .gitignore        # Ignores beads.db
+├── config.yaml
+├── issues.jsonl
+├── metadata.json
+├── team-map.jsonl
+├── hooks/
+└── .gitignore
+```
+
+Legacy local database cache files are no longer part of the supported Forge setup instructions. When you need JSONL snapshots for migration verification or CI diffing, generate them explicitly with `bd backup --force`.
+
+### Migrate Legacy SQLite Data
+
+Use the repo wrapper instead of hand-editing `.beads/`:
+
+```bash
+bash scripts/beads-migrate-to-dolt.sh
 ```
 
-**Dual-database architecture**: JSONL for git versioning, SQLite for fast local queries. Background daemon keeps them in sync.
+Default paths used by the wrapper:
+
+- `--project-root`: current working directory
+- `--legacy-backup-dir`: `.beads/backup`
+- `--snapshot-root`: `.beads-migration-snapshots`
+- `--migrated-dir`: `.beads-migrated`
+- `--export-dir`: `.beads-migrated-export`
+
+What the wrapper does:
 
-### Complete Command Reference
+1. Snapshots the current `.beads/` directory into `.beads-migration-snapshots/<timestamp>/current-beads`.
+2. Restores the legacy JSONL backup into a fresh migrated workspace.
+3. Exports a fresh backup snapshot for parity verification.
+4. Verifies issue IDs, dependency edges, comment IDs, config keys, and record counts.
+5. Writes `.beads-migrated/migration-manifest.json` on success.
 
-#### Initialization
+rollback behavior:
+
+- The wrapper automatically restores the pre-migration `.beads/` snapshot if parity verification fails.
+- If you need to inspect or restore manually, use the timestamped snapshot under `.beads-migration-snapshots/`.
+
+See the script help for explicit path overrides:
 
 ```bash
-bd init                    # Initialize in project
-bd init --stealth          # Local-only (don't commit to repo)
-bd init --contributor      # Contributor mode
-bd init --prefix PROJ      # Custom issue prefix (PROJ-xxx)
+bash scripts/beads-migrate-to-dolt.sh --help
 ```
 
-#### Issue Management
+### Post-Upgrade Smoke Verification
+
+Run the repo smoke harness after upgrading:
 
 ```bash
-# Create issues
-bd create "Title"                           # Basic issue
-bd create "Title" --type feature            # With type (feature, bug, chore, etc.)
-bd create "Title" --priority 1              # With priority (0=critical, 4=backlog)
-bd create "Title" -p 0 -l "urgent,backend"  # P0 with labels
-
-# View issues
-bd show <id>                   # Detailed view with audit trail
-bd list                        # All issues
-bd list --status open          # Filter by status
-bd list --priority 1           # Filter by priority
-bd list --assignee bob         # Filter by assignee
-bd list --label bug            # Filter by label (AND logic)
-bd list --label-any bug,urgent # Filter by label (OR logic)
-bd list --type feature         # Filter by type
-bd list --title-contains "auth" # Search titles
-bd list --limit 10             # Limit results
-
-# Update issues
-bd update <id> --status in_progress     # Change status
-bd update <id> --priority 2             # Change priority
-bd update <id> --assignee bob           # Assign
-bd update <id> --title "New title"      # Update title
-bd update <id> --description "..."      # Update description
-bd update <id> --notes "..."            # Add notes
-bd update <id> --label-add urgent       # Add label
-
-# Complete issues
-bd close <id>                           # Close single issue
-bd close <id1> <id2> <id3>              # Close multiple (efficient)
-bd close <id> --reason "Completed auth" # Close with reason
-bd delete <id>                          # Delete issue
-bd delete <id> --cascade                # Delete with dependents
-```
-
-#### Workflow Commands
+bash scripts/beads-upgrade-smoke.sh
+```
+
+The harness records a machine-readable summary at `.artifacts/beads-upgrade-smoke/summary.json` by default and exercises this sequence:
+
+1. `bd create` primary smoke issue
+2. `bd create` dependent smoke issue
+3. `bd list --json --limit=0`
+4. `bd show <id> --json`
+5. `bd dep add <child> <parent>`
+6. `bd close <id>` cleanup for both smoke issues
+7. `bd sync` compatibility check
+
+If any command fails, the summary captures `failedStep`, command output, and cleanup state. This is intentional: the harness does not silently substitute a different command for `bd sync`.
+
+### Day-to-Day Commands
 
 ```bash
 # Find work
-bd ready                        # Issues with NO open blockers (start here!)
-bd ready --priority 1           # Filter ready work by priority
-bd blocked                      # Issues that ARE blocked
-
-# Dependencies
-bd dep add <child> <parent>                    # child depends on parent (blocks)
-bd dep add <child> <parent> --type related     # Soft reference (no blocking)
-bd dep add <child> <parent> --type parent-child # Hierarchical
-bd dep remove <child> <parent>                 # Remove dependency
-bd dep tree <id>                               # Visualize dependency tree
-bd dep cycles                                  # Detect cycles
-
-# Comments
-bd comments <id>                # View comments
-bd comments <id> "Comment text" # Add comment
-
-# Git sync
-bd sync                         # Export to JSONL, commit, push
-bd sync --status                # Check sync status
-bd hooks install                # Install git hooks for auto-sync
-
-# Maintenance
-bd stats                        # Project statistics
-bd doctor                       # Check for issues
-bd admin compact --days 90      # Compact old closed issues
-```
-
-#### Issue Statuses
-
-- `open` - Not started
-- `in_progress` - Being worked on
-- `blocked` - Waiting on something
-- `completed` - Done
-- `on_hold` - Paused
-- `cancelled` - Won't do
-
-#### Priority Levels
-
-| Priority | Meaning | Usage |
-|----------|---------|-------|
-| 0 (P0) | Critical | Drop everything, fix now |
-| 1 (P1) | High | Do this sprint |
-| 2 (P2) | Medium | Planned work |
-| 3 (P3) | Low | Nice to have |
-| 4 (P4) | Backlog | Someday/maybe |
-
-#### Dependency Types
-
-| Type | Blocks Ready? | Use Case |
-|------|---------------|----------|
-| `blocks` | YES | Hard dependency |
-| `related` | NO | Soft reference |
-| `parent-child` | YES | Hierarchy |
-| `discovered-from` | NO | Found during work |
+forge ready
+forge show <id>
+forge claim <id>
+
+# Issue operations
+forge create "Title"
+forge list
+forge update <id> --priority 2
+forge close <id>
+
+# Direct beads operations
+bd comments add <id> "Progress update"
+bd dep add <child> <parent>
+bd dep cycles
+bd backup --force
+bd dolt status
+
+# Routine repo sync
+forge sync
+```
 
 ### Session Workflow
 
 ```bash
 # Start of session
-bd ready                    # What can I work on?
-bd show <id>                # Review the issue
-bd update <id> --status in_progress
+forge ready
+forge show <id>
+forge claim <id>
 
 # During work
-bd comments <id> "Progress update"
-bd update <id> --notes "Found edge case"
+bd comments add <id> "Progress update"
+forge update <id> --notes "Found edge case"
 
 # End of session
-bd close <id>               # If done, or:
-bd update <id> --status blocked --comment "Needs API response"
-bd sync                     # Always sync at end!
+forge close <id>
+forge sync
 ```
 
 ---
@@ -541,7 +526,7 @@ gh issue create --title "..." --body "..."
 
 ### Beads (`bd`) — Minimum Version
 
-**Minimum version**: v0.49.x
+**Recommended stable version**: `v1.0.0`
 **Check installed version**:
 ```bash
 bd --version
@@ -549,14 +534,17 @@ bd --version
 
 **Install / Update**:
 ```bash
-# macOS / Linux
-bun add -g @beads/bd
+# Recommended
+bunx forge setup
 
 # Windows — use PowerShell installer (npm has EPERM bug)
 irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
 ```
 
-> **Why v0.49.x?** Earlier versions lack the `bd ready` dependency-aware query, `bd sync --status`, and the dual-database (JSONL + SQLite) architecture that Forge relies on.
+> **Why Forge + Beads?** Forge wraps the supported day-to-day issue workflow
+> (`forge ready`, `forge create`, `forge close`, `forge sync`) while Beads
+> remains the underlying store for initialization, dependencies, comments, and
+> Dolt-backed sync internals.
 
 ---
 
@@ -564,14 +552,14 @@ irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
 
 | Stage | Tools Used |
 |-------|------------|
-| `/status` | `bd ready`, `bd list`, `git status` |
+| `/status` | `forge ready`, `forge list`, `git status` |
 | `/plan` (Phase 2) | Parallel AI, Context7, grep.app, codebase exploration |
-| `/plan` | `bd create`, `git checkout -b` |
-| `/dev` | Tests, code, `bd update`, `/tasks save` |
+| `/plan` | `forge create`, `git checkout -b` |
+| `/dev` | Tests, code, `forge update`, `/tasks save` |
 | `/validate` | Type check, lint, tests, SonarCloud |
-| `/ship` | `bd update --status done`, `gh pr create` |
+| `/ship` | `forge close`, `gh pr create` |
 | `/review` | `gh pr view`, Greptile, SonarCloud |
-| `/premerge` | `bd sync`, doc updates, hand off PR |
+| `/premerge` | `forge sync`, doc updates, hand off PR |
 | `/verify` | Documentation cross-check |
 
 ---
@@ -582,13 +570,15 @@ irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
 
 ```bash
 bd init                     # Initialize
-bd ready                    # Find unblocked work
-bd create "Title"           # Create issue
-bd show <id>                # View details
-bd update <id> --status X   # Update status
+forge ready                 # Find unblocked work
+forge create "Title"        # Create issue
+forge show <id>             # View details
+forge update <id> --status X   # Update status
 bd dep add <a> <b>          # a depends on b
-bd close <id>               # Complete
-bd sync                     # Git sync
+forge close <id>            # Complete
+forge sync                  # Routine repo sync
+bash scripts/beads-migrate-to-dolt.sh
+bash scripts/beads-upgrade-smoke.sh
 ```
 
 ### GitHub CLI
@@ -626,12 +616,12 @@ irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
 
 **"database locked"**
 ```bash
-bd sync --force
+forge sync
 ```
 
 **Issues not showing after git pull**
 ```bash
-bd sync  # Re-imports from JSONL
+forge sync  # Re-syncs Beads state through the Forge wrapper
 ```
 
 ### GitHub CLI

package/lib/agents/codex.plugin.json

@@ -12,6 +12,9 @@
   "directories": {
     "skills": ".codex/skills"
   },
+  "installTargets": {
+    "skills": "$CODEX_HOME/skills"
+  },
   "setup": {
     "copyRules": false,
     "createSkill": true

package/lib/agents-config.js

@@ -220,16 +220,19 @@ Configuration: \`.mcp.json\` or agent-specific config files
 
 ## Issue Tracking
 
-Use **Beads** for persistent tracking across sessions:
+Use **Forge's Beads wrapper** for persistent tracking across sessions:
 
 \`\`\`bash
-bd create "Feature name"              # Create issue
-bd update <id> --status in_progress   # Claim work
-bd update <id> --comment "Progress"   # Add notes
-bd close <id>                          # Complete
-bd sync                                # Sync with git
+forge create "Feature name"              # Create issue
+forge claim <id>                         # Claim work
+forge update <id> --append-notes "Progress" # Add notes
+forge close <id>                         # Complete
+forge sync                               # Sync Beads state
 \`\`\`
 
+Use \`bd\` directly only for capabilities Forge does not wrap yet, such as
+\`bd init\`, \`bd comments\`, \`bd dep\`, and \`bd dolt\`.
+
 ## Git Workflow
 
 **Branch naming**:
@@ -480,16 +483,19 @@ Configure these MCP servers in \`.mcp.json\`:
 
 ## Issue Tracking with Beads
 
-Use **Beads** for persistent tracking across sessions:
+Use **Forge's Beads wrapper** for persistent tracking across sessions:
 
 \`\`\`bash
-bd create "Feature name"                  # Create issue
-bd update <id> --status in_progress       # Claim work
-bd update <id> --append-notes "Progress"  # Add notes
-bd close <id>                              # Complete
-bd sync                                    # Sync with git
+forge create "Feature name"                # Create issue
+forge claim <id>                           # Claim work
+forge update <id> --append-notes "Progress" # Add notes
+forge close <id>                           # Complete
+forge sync                                 # Sync Beads state
 \`\`\`
 
+Use \`bd\` directly only for capabilities Forge does not wrap yet, such as
+\`bd init\`, \`bd comments\`, \`bd dep\`, and \`bd dolt\`.
+
 ## Code Quality Standards
 
 ${meta.language === 'TypeScript' ? `