forge-workflow 0.0.8 → 0.0.10

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/README.md

@@ -402,14 +402,20 @@ gh auth login
 /premerge <pr>             # Complete docs, hand off PR
 /verify                    # Post-merge health check
 
-# Beads commands (optional)
-bd init                    # Initialize tracking
-bd ready                   # Find ready work
-bd create "title"          # Create issue
-bd update <id> --status X  # Update status
-bd sync                    # Sync with git
+# Issue commands (via Forge)
+bd init                    # Initialize Beads tracking
+forge ready                # Find ready work
+forge create "title"       # Create issue
+forge update <id> --status X  # Update status
+forge sync                 # Sync Beads state
 ```
 
+For advanced Beads operations that Forge does not wrap yet, use `bd` directly for
+`bd comments`, `bd dep`, and `bd dolt`.
+
+Forge is the preferred command surface for routine workflows, but Beads (`bd`)
+remains the underlying source of truth for issue state and IDs.
+
 ---
 
 ## License

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');
@@ -139,7 +139,7 @@ function loadAgentsFromPlugins() {
     agents[id] = {
       name: plugin.name,
       description: plugin.description || '',
-      dirs: Object.values(plugin.directories || {}),
+      dirs: getRepoRelativePluginDirectories(plugin),
       hasCommands: plugin.capabilities?.commands || plugin.setup?.copyCommands || false,
       hasSkill: plugin.capabilities?.skills || plugin.setup?.createSkill || false,
       linkFile: plugin.files?.rootConfig || '',
@@ -153,6 +153,17 @@ function loadAgentsFromPlugins() {
   return agents;
 }
 
+function isRepoRelativePluginPath(candidate) {
+  return typeof candidate === 'string'
+    && candidate.length > 0
+    && !path.isAbsolute(candidate)
+    && !/^[~$%]/.test(candidate);
+}
+
+function getRepoRelativePluginDirectories(plugin) {
+  return Object.values(plugin.directories || {}).filter(isRepoRelativePluginPath);
+}
+
 // Agent definitions - loaded from plugin system
 const AGENTS = loadAgentsFromPlugins();
 
@@ -2383,7 +2394,7 @@ function displaySetupSummary(selectedAgents) {
 
   // Beads status
   if (isBeadsInitialized()) {
-    console.log('  ✓ Beads initialized - Track work: bd ready');
+    console.log('  ✓ Beads initialized - Track work: forge ready');
   } else if (checkForBeads()) {
     console.log('  ! Beads available - Run: bd init');
   } else {
@@ -2543,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;
   }
@@ -3336,7 +3347,7 @@ async function setupProjectTools(rl, question) {
   console.log('');
   console.log('• Beads - Git-backed issue tracking');
   console.log('  Persists tasks across sessions, tracks dependencies.');
-  console.log('  Command: bd ready, bd create, bd close');
+  console.log('  Command: forge ready, forge create, forge close');
   console.log('');
   console.log('• Skills - Universal SKILL.md management');
   console.log('  Manage AI agent skills across all agents.');
@@ -4036,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}`);
@@ -4802,4 +4813,9 @@ if (require.main === module) {
   })();
 }
 
-module.exports = { getWorkflowCommands, ensureDirWithNote };
+module.exports = {
+  ensureDirWithNote,
+  getWorkflowCommands,
+  validateDirectoryPathInput,
+  validateUserInput,
+};

package/docs/BEADS_GITHUB_SYNC.md

@@ -3,10 +3,14 @@
 Automatic synchronization between GitHub Issues and Beads issue tracking.
 
 **GitHub Issues** = human/team/public interface.
-**Beads** = AI agent engine (`bd ready`, `bd close`).
+**Beads** = issue engine behind Forge (`forge ready`, `forge close`).
 
 Neither side needs to know about the other. Contributors file issues on GitHub; AI agents pick up work via Beads. Status changes propagate automatically.
 
+For human and agent workflows, prefer the Forge wrapper commands (`forge ready`,
+`forge create`, `forge close`, `forge sync`). The workflow automation shown below
+still calls `bd` directly as an internal implementation detail.
+
 ---
 
 ## Architecture
@@ -48,7 +52,7 @@ sequenceDiagram
     participant WF as GitHub Actions
     participant GH as GitHub Issues
 
-    AI->>BD: bd close forge-abc
+    AI->>BD: forge close forge-abc
     BD->>Repo: Update issues.jsonl
     AI->>Repo: git push
     Repo->>WF: push trigger (paths: .beads/**)
@@ -65,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/EXAMPLES.md

@@ -109,7 +109,7 @@ git commit -m "feat: add health check endpoint"
 /status
 
 # If Beads installed:
-bd create "SQL injection in search endpoint" \
+forge create "SQL injection in search endpoint" \
   --type bug \
   --priority 0 \
   --label "security,critical"
@@ -224,7 +224,7 @@ OWASP A03:2021 Injection"
 # ═══════════════════════════════════════════════════════════
 /status
 
-bd create "Extract auth logic to service" \
+forge create "Extract auth logic to service" \
   --type chore \
   --priority 2
 
@@ -337,35 +337,35 @@ Team of 3 developers:
 # PROJECT SETUP (Once per project)
 # ═══════════════════════════════════════════════════════════
 bd init --prefix SHOP
-bd sync  # Commit .beads/ to git
+forge sync  # Sync initial Beads state
 
 # ═══════════════════════════════════════════════════════════
 # ALICE: Payment Integration
 # ═══════════════════════════════════════════════════════════
 
 # Morning: Check what's available
-bd ready
+forge ready
 # Output:
 # SHOP-1: Payment integration (ready)
 # SHOP-3: Admin dashboard (ready)
 
 # Claim work
-bd update SHOP-1 --status in_progress
+forge claim SHOP-1
 /status
 /plan stripe-payment-integration
 /dev
 
 # Midday: Progress update
-bd comments SHOP-1 "Stripe SDK integrated, working on webhooks"
+bd comments add SHOP-1 "Stripe SDK integrated, working on webhooks"
 
 # Afternoon: Blocked on API keys
-bd update SHOP-1 --status blocked --comment "Need production Stripe API keys"
+forge update SHOP-1 --status blocked --comment "Need production Stripe API keys"
 
 # Create dependency
-bd create "Get Stripe API keys from DevOps" --type chore --priority 1
+forge create "Get Stripe API keys from DevOps" --type chore --priority 1
 bd dep add SHOP-1 SHOP-5  # SHOP-1 depends on SHOP-5
 
-bd sync  # Push to git
+forge sync  # Push Beads state
 
 # ═══════════════════════════════════════════════════════════
 # BOB: Email Notifications (Same Time)
@@ -373,24 +373,24 @@ bd sync  # Push to git
 
 # Morning: Pull latest, check work
 git pull
-bd sync  # Sync with Alice's updates
+forge sync  # Sync with Alice's updates
 
-bd ready
+forge ready
 # Output:
 # SHOP-3: Admin dashboard (ready)
 # SHOP-2: Email notifications (ready)
 
 # Claim different feature
-bd update SHOP-2 --status in_progress
+forge claim SHOP-2
 /plan email-notifications
 /dev
 
 # No conflicts with Alice (different files)
 
 # End of day: Complete
-bd close SHOP-2 --reason "Implemented with SendGrid"
+forge close SHOP-2 --reason "Implemented with SendGrid"
 /ship
-bd sync
+forge sync
 
 # ═══════════════════════════════════════════════════════════
 # CHARLIE: Admin Dashboard (Next Day)
@@ -398,17 +398,17 @@ bd sync
 
 # Morning: Check dependencies
 git pull
-bd sync
+forge sync
 
-bd show SHOP-3
+forge show SHOP-3
 # Output:
 # Status: ready
 # Depends on: (none)
 
-bd update SHOP-3 --status in_progress
+forge claim SHOP-3
 
 # Discovers overlap with Bob's work
-bd comments SHOP-3 "Need Bob's email service for user notifications"
+bd comments add SHOP-3 "Need Bob's email service for user notifications"
 bd dep add SHOP-3 SHOP-2  # SHOP-3 depends on SHOP-2
 
 # Bob's work already merged, so can proceed
@@ -428,7 +428,7 @@ bd blocked
 # SHOP-1: Payment integration (blocked by SHOP-5)
 
 # Find work with no blockers:
-bd ready
+forge ready
 
 # See full project status:
 bd stats
@@ -440,7 +440,7 @@ bd stats
 # Done: 4
 
 # Always sync at end of session:
-bd sync
+forge sync
 ```
 
 **Result**: Team can work in parallel, track dependencies, and avoid conflicts.
@@ -465,8 +465,8 @@ bd sync
 
 ### 4. Team Collaboration
 - Beads tracks dependencies
-- `bd ready` finds available work
-- `bd sync` at end of every session
+- `forge ready` finds available work
+- `forge sync` at end of every session
 - Comments keep teammates informed
 
 ---

package/docs/ROADMAP.md

@@ -291,8 +291,8 @@ All PRs tracked in Beads with proper dependencies:
 | PR8 | forge-dwm | Blocked | P3 | PR7 |
 | ~~Skills CLI~~ | ~~forge-mlm~~ | ~~Absorbed into PR5.5 + PR6 + PR8~~ | — | — |
 
-**View all issues**: `bd list`
-**View ready work**: `bd ready`
+**View all issues**: `forge list`
+**View ready work**: `forge ready`
 **View blocked issues**: `bd blocked`
 
 ### Git Workflow
@@ -348,7 +348,7 @@ Each PR is self-contained and can be rolled back independently:
 ## Resources
 
 - **Master Plan**: `docs/plans/*.md`
-- **Beads Issues**: `bd list` or `bd show <issue-id>`
+- **Beads Issues**: `forge list` or `forge show <issue-id>`
 - **Workflow Guide**: [AGENTS.md](../AGENTS.md)
 - **Architecture Docs**: Coming in PR0 - [ARCHITECTURE.md](./ARCHITECTURE.md)