forge-workflow 0.0.9 → 0.0.10

package/.opencode/commands/status.md

@@ -20,7 +20,7 @@ This command helps you understand the current state of the project before starti
 
 ```bash
 # Sync team state before showing status
-bash scripts/sync-utils.sh auto-sync
+forge sync || true
 ```
 
 ### Step 1: Smart Status (ranked issues with conflict detection)
@@ -28,7 +28,7 @@ bash scripts/sync-utils.sh auto-sync
 ```bash
 bash scripts/smart-status.sh
 ```
-This script dynamically computes and displays all issues ranked by composite score (priority, dependency impact, type, staleness, epic proximity). Output includes active sessions, conflict risk annotations, and grouped categories. No manual querying needed — the script handles everything.
+This command dynamically computes and displays all issues ranked by composite score (priority, dependency impact, type, staleness, epic proximity). Output includes active sessions, conflict risk annotations, and grouped categories. No manual querying needed.
 
 For full context on any issue: `bd show <id>`
 
@@ -77,10 +77,10 @@ Show current developer's active work and team overview:
 
 ```bash
 # Show my active issues
-bash scripts/forge-team/index.sh workload --me 2>&1 || true
+forge team workload --me 2>&1 || true
 
 # One-line team summary
-bash scripts/forge-team/index.sh dashboard 2>&1 | head -5 || true
+forge team dashboard 2>&1 | head -5 || true
 ```
 
 ## Next Steps

package/.roo/commands/dev.md

@@ -70,8 +70,8 @@ Do NOT write any code until ALL confirmed:
 Before starting the per-task loop, check for cross-developer conflicts:
 
 ```bash
-# Auto-sync to get latest team state
-bash scripts/sync-utils.sh auto-sync
+# Auto-sync to get latest team state (non-blocking)
+forge sync || true
 
 # Check for conflicts with the current beads issue
 bash scripts/conflict-detect.sh --issue <beads-id>

package/.roo/commands/plan.md

@@ -58,7 +58,7 @@ Before proceeding to Phase 1, check for cross-developer conflicts:
 
 ```bash
 # Auto-sync to get latest team state
-bash scripts/sync-utils.sh auto-sync
+forge sync || true
 
 # Check for conflicts with this issue's planned work area
 bash scripts/conflict-detect.sh --issue <beads-id>
@@ -108,7 +108,7 @@ If merge conflicts or unmet dependencies are found:
 Before starting planning, verify team identity is mapped:
 
 ```bash
-bash scripts/forge-team/index.sh verify 2>&1 || true
+forge team verify 2>&1 || true
 ```
 
 If verify reports issues, address them before proceeding (the output will include `FORGE_AGENT_7f3a:PROMPT:` directives with exact commands to run).

package/.roo/commands/ship.md

@@ -167,10 +167,10 @@ After PR is created, sync issue state to GitHub and verify 1:1 mapping:
 
 ```bash
 # Sync issue state to GitHub
-bash scripts/forge-team/index.sh sync 2>&1 || true
+forge team sync 2>&1 || true
 
 # Verify 1:1 mapping
-bash scripts/forge-team/index.sh verify 2>&1 || true
+forge team verify 2>&1 || true
 ```
 
 ## Example Output

package/.roo/commands/status.md

@@ -21,7 +21,7 @@ This command helps you understand the current state of the project before starti
 
 ```bash
 # Sync team state before showing status
-bash scripts/sync-utils.sh auto-sync
+forge sync || true
 ```
 
 ### Step 1: Smart Status (ranked issues with conflict detection)
@@ -29,7 +29,7 @@ bash scripts/sync-utils.sh auto-sync
 ```bash
 bash scripts/smart-status.sh
 ```
-This script dynamically computes and displays all issues ranked by composite score (priority, dependency impact, type, staleness, epic proximity). Output includes active sessions, conflict risk annotations, and grouped categories. No manual querying needed — the script handles everything.
+This command dynamically computes and displays all issues ranked by composite score (priority, dependency impact, type, staleness, epic proximity). Output includes active sessions, conflict risk annotations, and grouped categories. No manual querying needed.
 
 For full context on any issue: `bd show <id>`
 
@@ -78,10 +78,10 @@ Show current developer's active work and team overview:
 
 ```bash
 # Show my active issues
-bash scripts/forge-team/index.sh workload --me 2>&1 || true
+forge team workload --me 2>&1 || true
 
 # One-line team summary
-bash scripts/forge-team/index.sh dashboard 2>&1 | head -5 || true
+forge team dashboard 2>&1 | head -5 || true
 ```
 
 ## Next Steps

package/AGENTS.md

@@ -269,4 +269,5 @@ forge close <id>      # Complete work
 - 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
+- After fixing review feedback, always push the changes and resolve the related GitHub review threads via the GraphQL API before considering the work complete
 <!-- END BEADS INTEGRATION -->

package/CLAUDE.md

@@ -50,6 +50,17 @@ See [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md) for detailed MCP setup instructions.
 
 Setup prompts for Beads during interactive installation. Manual install: see [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md).
 
+### Shell Model
+
+Forge commands and repo scripts assume the following shell model:
+
+| Platform | Shell used by Forge commands and scripts |
+| --- | --- |
+| Windows | Git Bash for helper-backed Forge stage flows |
+| macOS/Linux | Default login shell |
+
+On Windows, Forge runtime health enforces Git Bash for helper-backed stage flows. Native PowerShell is still used by some bootstrap paths, and WSL may be useful for adjacent development tasks. See [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md#shell-model) for details.
+
 ---
 
 ## Git Workflow
@@ -106,5 +117,6 @@ As you work, when you give the same instruction twice, add it here:
 - **Pre-push test env**: `test-env/` fixture tests can fail during actual `git push` due to git mid-push state. Fix the root cause — never use `LEFTHOOK=0`.
 - **Command sync**: After editing `.claude/commands/*.md`, run `node scripts/sync-commands.js` to update all 7 agent directories. Use `--check` in CI to detect drift. Use `--dry-run` to preview.
 - **Dynamic commands**: Never hardcode example output in command files (`.claude/commands/*.md`) when a script generates that output dynamically. Command files should reference the script and describe what it does — not duplicate its output with fake data that becomes stale.
+- **Review follow-up completion**: After fixing review feedback, always push the changes and resolve the related GitHub review threads via the GraphQL API before considering the work complete.
 
 <!-- USER:END -->

package/bin/forge.js

@@ -64,7 +64,7 @@ const { createSymlinkOrCopy: libCreateSymlinkOrCopy } = require(path.join(packag
 const beadsSetupLib = require(path.join(packageDir, 'lib', 'beads-setup'));
 const { beadsHealthCheck } = require(path.join(packageDir, 'lib', 'beads-health-check'));
 const { setupPAT } = require(path.join(packageDir, 'lib', 'pat-setup'));
-const { detectDefaultBranch, detectBeadsVersion, templateWorkflows, scaffoldBeadsSync } = require(path.join(packageDir, 'lib', 'beads-sync-scaffold'));
+const { DEFAULT_BEADS_VERSION, detectDefaultBranch, templateWorkflows, scaffoldBeadsSync } = require(path.join(packageDir, 'lib', 'beads-sync-scaffold'));
 
 // Load incremental setup modules
 const { detectEnvironment } = require('../lib/detect-agent');
@@ -2554,7 +2554,7 @@ function parseFlags() {
 
   // Issue passthrough commands delegate all flags to bd.
   // Skip global parsing so flags like --type, -p, --help reach the handler intact.
-  const issuePassthroughCommands = ['create', 'update', 'claim', 'close', 'show', 'list', 'ready', 'issue'];
+  const issuePassthroughCommands = ['create', 'update', 'claim', 'close', 'show', 'list', 'ready', 'issue', 'issues'];
   if (issuePassthroughCommands.includes(args[0])) {
     return flags;
   }
@@ -4047,9 +4047,9 @@ async function handleSyncScaffold() {
       console.log(`  Skipped: ${f} (already exists)`);
     }
 
-    // Detect default branch and Beads version, then template workflows
+    // Detect default branch and pin forge-managed workflows to the repo baseline Beads version.
     const branch = detectDefaultBranch(projectRoot);
-    const beadsVersion = detectBeadsVersion();
+    const beadsVersion = DEFAULT_BEADS_VERSION;
     const workflowDir = path.join(projectRoot, '.github', 'workflows');
     templateWorkflows(workflowDir, branch, beadsVersion, result.filesCreated || []);
     console.log(`  Branch: ${branch}, Beads version: ${beadsVersion}`);
@@ -4813,4 +4813,9 @@ if (require.main === module) {
   })();
 }
 
-module.exports = { getWorkflowCommands, ensureDirWithNote };
+module.exports = {
+  ensureDirWithNote,
+  getWorkflowCommands,
+  validateDirectoryPathInput,
+  validateUserInput,
+};

package/docs/BEADS_GITHUB_SYNC.md

@@ -69,6 +69,32 @@ Three guards prevent infinite ping-pong:
 2. **Commit message prefix** -- Phase 2 workflow skips commits starting with `chore(beads):`
 3. **Opt-out label** -- `skip-beads-sync` label on any issue disables sync entirely
 
+### Normalized Core
+
+GitHub-owned shared fields are the only fields that steady-state pull and initial import are allowed to overwrite:
+
+- `github.number`
+- `github.nodeId`
+- `github.url`
+- `shared.title`
+- `shared.body`
+- `shared.state`
+- `shared.assignees`
+- `shared.labels`
+- `shared.milestone`
+- `sync.remoteUpdatedAt`
+
+Forge-owned workflow context stays local in Beads. That includes workflow stage, dependencies, progress notes, decisions, and other issue-engine metadata.
+
+Both ongoing pull sync and the `forge-ij1` import bootstrap use the same primitive layer:
+
+- `lib/issue-sync/link-store.js` resolves canonical GitHub/Beads links.
+- `lib/issue-sync/github-pull.js` normalizes remote GitHub issues into shared records.
+- `lib/issue-sync/reconcile.js` applies GitHub-owned fields and materializes the local cache row.
+- `lib/issue-sync/import-primitives.js` exposes `listRemoteIssues`, `normalizeRemoteIssue`, `resolveSharedLink`, and `materializeLocalIssue` for import backfill.
+
+`forge-ij1` depends on these primitives directly. It does not use a separate import-specific sync contract or an alternate reconciliation path.
+
 ---
 
 ## Setup

package/docs/TOOLCHAIN.md

@@ -31,185 +31,166 @@ 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** - `forge 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
 ```
 
-**Dual-database architecture**: JSONL for git versioning, SQLite for fast local queries. Background daemon keeps them in sync.
+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
+```
 
-For day-to-day issue workflows, prefer the Forge wrapper commands (`forge ready`,
-`forge create`, `forge update`, `forge close`, `forge sync`). Use `bd` directly
-for Beads capabilities Forge does not wrap yet, such as `bd init`, `bd comments`,
-`bd dep`, `bd blocked`, and `bd dolt *`.
+Default paths used by the wrapper:
 
-### Complete Command Reference
+- `--project-root`: current working directory
+- `--legacy-backup-dir`: `.beads/backup`
+- `--snapshot-root`: `.beads-migration-snapshots`
+- `--migrated-dir`: `.beads-migrated`
+- `--export-dir`: `.beads-migrated-export`
 
-#### Initialization
+What the wrapper does:
+
+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.
+
+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
-forge create "Title"                           # Basic issue
-forge create "Title" --type feature            # With type (feature, bug, chore, etc.)
-forge create "Title" --priority 1              # With priority (0=critical, 4=backlog)
-forge create "Title" -p 0 -l "urgent,backend"  # P0 with labels
-
-# View issues
-forge show <id>                   # Detailed view with audit trail
-forge list                        # All issues
-forge list --status open          # Filter by status
-forge list --priority 1           # Filter by priority
-forge list --assignee bob         # Filter by assignee
-forge list --label bug            # Filter by label (AND logic)
-forge list --label-any bug,urgent # Filter by label (OR logic)
-forge list --type feature         # Filter by type
-forge list --title-contains "auth" # Search titles
-forge list --limit 10             # Limit results
-
-# Update issues
-forge claim <id>                        # Claim work (sets in_progress)
-forge update <id> --priority 2          # Change priority
-forge update <id> --assignee bob        # Assign
-forge update <id> --title "New title"   # Update title
-forge update <id> --description "..."   # Update description
-forge update <id> --notes "..."         # Add notes
-forge update <id> --add-label urgent    # Add label
-
-# Complete issues
-forge close <id>                           # Close single issue
-forge close <id1> <id2> <id3>              # Close multiple (efficient)
-forge 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
-forge ready                     # Issues with NO open blockers (start here!)
-forge 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 add <id> "Comment text" # Add comment
-
-# Git sync
-forge sync                      # Pull + push Beads state through the Forge wrapper
-bd dolt status                  # Check Dolt sync/server 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
-forge ready                 # What can I work on?
-forge show <id>             # Review the issue
+forge ready
+forge show <id>
 forge claim <id>
 
 # During work
@@ -217,9 +198,8 @@ bd comments add <id> "Progress update"
 forge update <id> --notes "Found edge case"
 
 # End of session
-forge close <id>            # If done, or:
-forge update <id> --status blocked --comment "Needs API response"
-forge sync                  # Always sync at end!
+forge close <id>
+forge sync
 ```
 
 ---
@@ -546,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
@@ -554,8 +534,8 @@ 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
@@ -596,7 +576,9 @@ forge show <id>             # View details
 forge update <id> --status X   # Update status
 bd dep add <a> <b>          # a depends on b
 forge close <id>            # Complete
-forge sync                  # Beads sync
+forge sync                  # Routine repo sync
+bash scripts/beads-migrate-to-dolt.sh
+bash scripts/beads-upgrade-smoke.sh
 ```
 
 ### GitHub CLI