forge-workflow 0.0.5 → 0.0.6

package/.roo/commands/ship.md

@@ -47,6 +47,36 @@ BEHIND=$(git rev-list --count HEAD..origin/"$BASE")
 
 This is NOT a full rebase — just a check. The rebase happens in /validate where the full test suite runs afterward.
 
+### Parallel PR coordination (soft block)
+
+Before creating the PR, check merge readiness:
+
+```bash
+# Run merge simulation against base branch
+bash scripts/pr-coordinator.sh merge-sim "$(git branch --show-current)" 2>&1
+
+# Show recommended merge order
+bash scripts/pr-coordinator.sh merge-order 2>&1 || true
+
+# Auto-label the PR after creation (called after gh pr create below)
+# bash scripts/pr-coordinator.sh auto-label <issue-id>
+```
+
+If merge simulation finds conflicts:
+- Display conflicted files
+- Ask: "Merge conflicts detected with base branch. These PRs should merge first: [list]. Proceed with PR creation anyway? (y/n)"
+- If `n`: exit cleanly
+- If `y`: log override via `bd comments add <id> "Ship override: creating PR despite merge conflicts"`, then continue
+
+After PR creation completes:
+```bash
+# Auto-label the newly created PR
+bash scripts/pr-coordinator.sh auto-label <issue-id>
+
+# Check for stale worktrees (informational)
+bash scripts/pr-coordinator.sh stale-worktrees 2>&1 || true
+```
+
 ### Step 3: Update Beads
 ```bash
 bd update <id> --status done
@@ -61,68 +91,86 @@ Use `--force-with-lease` because `/validate` may have rebased the branch, rewrit
 git push --force-with-lease -u origin <branch-name>
 ```
 
-### Step 5: Create PR
+### Step 5: Create PR Using Project's PR Template
 
-Use the narrative PR template below. Lead with WHY (Problem/Root Cause/Fix/Value) — this is what reviewers need to understand first. Keep implementation details (test coverage, security review, design doc) in a collapsible section so they're available but don't clutter the summary.
+**CRITICAL**: Always use the project's own PR template. Never use a hardcoded body.
 
-If no Beads issue exists (hotfix, external contribution), skip the "Closes" line.
+**Step 5a: Locate the PR template**
 
+Check for a PR template in the project (in order of precedence):
 ```bash
-gh pr create --title "<type>: <concise description>" --body "$(cat <<'EOF'
-## Problem
-[What was broken, what need existed, or what user pain this addresses]
-
-## Root Cause
-[Why it happened, why it was missing, or what gap existed]
+# Check standard locations
+PR_TEMPLATE=""
+for path in .github/pull_request_template.md .github/PULL_REQUEST_TEMPLATE.md docs/pull_request_template.md pull_request_template.md; do
+  if [ -f "$path" ]; then
+    PR_TEMPLATE="$path"
+    break
+  fi
+done
+```
 
-## Fix
-[What this PR does to solve it — approach, not implementation details]
+**Step 5b: Read and populate the template**
 
-## Value
-[Who benefits, what improves, what risk is removed]
+If a PR template exists:
+1. **Read the template file** using the Read tool
+2. **Fill in every section** with actual data from the current PR context:
+   - Replace HTML comments (`<!-- ... -->`) with real content
+   - Check applicable checkboxes (`- [x]`)
+   - Fill in beads issue IDs (replace `beads-xxx` with actual ID)
+   - Fill in test results, validation status, and other concrete data
+   - Reference the design doc: `docs/plans/YYYY-MM-DD-<slug>-design.md`
+3. **Do NOT remove any sections** — fill them all, even if "N/A"
+4. **Do NOT restructure the template** — keep the project's chosen format
 
-## Beads
-Closes: <issue-id>
+If no PR template exists, use this minimal fallback:
+```
+## Summary
+[1-3 sentences: what this PR does and why]
 
-<details>
-<summary>Implementation Details</summary>
+## Changes
+[Bulleted list of key changes]
 
-### Test Coverage
-- Tests: [count] passing
-- Scenarios covered: [list key scenarios]
+## Testing
+[How it was tested, test results]
 
-### Security Review
-- OWASP Top 10: [summary — applicable risks and mitigations]
-- Automated scan: [result]
+## Beads
+Closes beads-xxx
 
-### Design Doc
-See: docs/plans/YYYY-MM-DD-<slug>-design.md
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+```
 
-### Decisions Log
-See: docs/plans/YYYY-MM-DD-<slug>-decisions.md (if any undocumented decisions arose during /dev)
+**Step 5c: Create the PR**
 
-### Key Decisions
-[From design doc — 3-5 key decisions with reasoning]
+```bash
+gh pr create --title "<type>: <concise description>" --body "<populated-template-content>"
+```
 
-### Documentation Updated
-[List docs updated in this PR, or "None — no doc-facing changes"]
+Rules for the PR body:
+- **Use the project's template structure** — never substitute your own format
+- **Fill in concrete data** — commit counts, test results, actual file paths, real beads IDs
+- **Check applicable checkboxes** — `[x]` for items that apply, `[ ]` for items that don't
+- **Include "Closes beads-xxx"** in the Beads section (required for auto-close in /verify)
 
-### Validation
-- [x] Type check passing
-- [x] Lint passing (0 errors, 0 warnings)
-- [x] All tests passing
-- [x] Security review completed
+### Step 6: Validate Context and Record Stage Transition
+```bash
+bash scripts/beads-context.sh validate <id>
+bash scripts/beads-context.sh stage-transition <id> ship review \
+  --summary "<PR created, checks pending>" \
+  --decisions "<template sections filled, beads linked>" \
+  --artifacts "<PR URL, branch name>" \
+  --next "<review focus areas>"
+```
 
-</details>
+### Team sync after PR
 
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-EOF
-)"
-```
+After PR is created, sync issue state to GitHub and verify 1:1 mapping:
 
-### Step 6: Record Stage Transition
 ```bash
-bash scripts/beads-context.sh stage-transition <id> ship review
+# Sync issue state to GitHub
+bash scripts/forge-team/index.sh sync 2>&1 || true
+
+# Verify 1:1 mapping
+bash scripts/forge-team/index.sh verify 2>&1 || true
 ```
 
 ## Example Output
@@ -157,9 +205,9 @@ Stage 7: /verify     → Post-merge CI check on main
 
 ## Tips
 
-- **Lead with why**: Problem → Root Cause → Fix → Value is what reviewers need first
-- **Collapsible details**: Design doc, decisions log, test coverage go in `<details>` — available but not in the way
-- **Document security**: OWASP Top 10 review in collapsible section
-- **Test coverage**: Show all test scenarios passing
+- **Use the project's PR template**: Always read `.github/pull_request_template.md` (or equivalent) and populate it — never substitute your own format
+- **Fill every section**: Even if "N/A" — empty/missing sections cause review friction
+- **Include "Closes beads-xxx"**: Required for auto-close in /verify
+- **Concrete data only**: Test counts, file paths, commit SHAs — not placeholder text
 - **Wait for checks**: Let GitHub Actions, Greptile, SonarCloud run
 - **NO auto-merge**: Always wait for /review phase

package/.roo/commands/status.md

@@ -25,6 +25,7 @@ bash scripts/sync-utils.sh auto-sync
 ```
 
 ### Step 1: Smart Status (ranked issues with conflict detection)
+
 ```bash
 bash scripts/smart-status.sh
 ```
@@ -32,6 +33,35 @@ This script dynamically computes and displays all issues ranked by composite sco
 
 For full context on any issue: `bd show <id>`
 
+### Step 1b: Reconcile stale in-progress issues
+
+Check if any in-progress issues were already merged but not closed (can happen if `/verify` was skipped or backup was restored from stale snapshot):
+
+```bash
+# Detect default branch dynamically (prefer main over master)
+DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||')
+if [ -z "$DEFAULT_BRANCH" ]; then
+  if git rev-parse --verify main >/dev/null 2>&1; then DEFAULT_BRANCH="main"
+  elif git rev-parse --verify master >/dev/null 2>&1; then DEFAULT_BRANCH="master"
+  else echo "ERROR: No main or master branch found — skipping stale reconciliation" >&2; DEFAULT_BRANCH=""; fi
+fi
+
+# For each in_progress issue, check if its PR was already merged
+if [ -n "$DEFAULT_BRANCH" ]; then
+  bd list --status=in_progress --json 2>/dev/null | jq -r '.[].id' | while read id; do
+    # Search git log for the issue ID in commit messages (fixed-strings for literal match)
+    if git log --oneline --first-parent "$DEFAULT_BRANCH" --fixed-strings --grep="$id" | grep -q .; then
+      echo "STALE: $id — found in git history, likely already merged"
+    fi
+  done
+fi
+```
+
+If stale issues are found, close them:
+```bash
+bd close <id> --force --reason="Already merged — detected during status reconciliation"
+```
+
 ### Step 2: Review Recent Commits
 ```bash
 git log --oneline -10
@@ -42,6 +72,18 @@ git log --oneline -10
 - **Continuing work**: In-progress issues found, resume where left off
 - **Review needed**: Work marked complete, needs review/merge
 
+### Team context
+
+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
+
+# One-line team summary
+bash scripts/forge-team/index.sh dashboard 2>&1 | head -5 || true
+```
+
 ## Next Steps
 
 - **If starting new work**: Run `/plan <feature-name>`

package/.roo/commands/validate.md

@@ -229,7 +229,13 @@ until ALL FOUR show fresh output in this session:
 "Should pass", "was passing earlier", and "I'm confident" are not evidence.
 Run the commands. Show the output. THEN declare done.
 
-5. Stage transition: Run `bash scripts/beads-context.sh stage-transition <id> validate ship` → exit 0 confirmed
+5. Context check: Run `bash scripts/beads-context.sh validate <id>` and address any warnings
+6. Stage transition: Run the following → exit 0 confirmed:
+   bash scripts/beads-context.sh stage-transition <id> validate ship \
+     --summary "<all checks pass/fail summary>" \
+     --decisions "<any failures diagnosed and fixed>" \
+     --artifacts "<scripts and commands run>" \
+     --next "<ship readiness notes>"
 </HARD-GATE>
 ```
 

package/.roo/commands/verify.md

@@ -146,19 +146,67 @@ Branch: <branch-name> deleted ✓
 bd create --title="Post-merge: <description of issue>" --type=bug --priority=1
 ```
 
-### Step 8: Close Beads Issue (if healthy)
+### Step 8: Close Beads Issues (if healthy)
 
-If everything is clean, close the Beads issue:
+If everything is clean, close all Beads issues referenced in the merged PR.
+
+**Auto-detect beads issues from PR body and branch name:**
+
+```bash
+# Get PR body and branch name
+PR_BODY=$(gh pr view <number> --json body --jq '.body')
+PR_BRANCH=$(gh pr view <number> --json headRefName --jq '.headRefName')
+
+# Extract beads IDs from PR body (matches "Closes beads-xxx", "closes forge-xxx", etc.)
+# Patterns: "Closes <prefix>-<id>", "Fixes <prefix>-<id>", "Resolves <prefix>-<id>"
+BEADS_IDS=$(echo "$PR_BODY" | grep -oiE '(closes|fixes|resolves):?\s+[a-z]+-[a-z0-9]+' | grep -oiE '[a-z]+-[a-z0-9]{3,6}$')
+
+# Validate each ID exists in beads
+VALID_IDS=""
+for id in $BEADS_IDS; do
+  if bd show "$id" >/dev/null 2>&1; then
+    VALID_IDS="$VALID_IDS $id"
+  fi
+done
+BEADS_IDS="$VALID_IDS"
+
+# Also check branch name for beads ID — extract segment after last /
+# then validate with bd show to avoid false matches like "pr-templa"
+BRANCH_SLUG=$(echo "$PR_BRANCH" | sed 's|.*/||')
+BRANCH_ID=$(echo "$BRANCH_SLUG" | grep -oE '[a-z]+-[a-z0-9]{3,6}' | head -1)
+if [ -n "$BRANCH_ID" ] && ! bd show "$BRANCH_ID" >/dev/null 2>&1; then
+  BRANCH_ID=""  # Not a valid beads ID — discard
+fi
+```
+
+**Close each matched issue:**
 
 ```bash
-bd close <id> --reason="Merged and verified on master"
+# Close issues found in PR body
+for id in $BEADS_IDS; do
+  bd close "$id" --reason="Merged and verified on master (PR #<number>)" 2>&1 || echo "Warning: could not close $id"
+done
+
+# If no issues found in body, try branch name match (skip if already closed above)
+if [ -z "$BEADS_IDS" ] && [ -n "$BRANCH_ID" ]; then
+  bd close "$BRANCH_ID" --reason="Merged and verified on master (PR #<number>)" 2>&1 || echo "Warning: could not close $BRANCH_ID"
+elif [ -n "$BRANCH_ID" ] && ! echo "$BEADS_IDS" | grep -qw "$BRANCH_ID"; then
+  bd close "$BRANCH_ID" --reason="Merged and verified on master (PR #<number>)" 2>&1 || echo "Warning: could not close $BRANCH_ID"
+fi
+```
+
+**If no beads issues detected at all**, prompt the user:
+```
+⚠ No beads issue ID found in PR body or branch name.
+  If this PR closes a beads issue, run: bd close <id> --reason="Merged and verified on master (PR #<number>)"
 ```
 
 ```
 <HARD-GATE: /verify exit>
 Do NOT declare /verify complete until:
 1. gh run list --branch master --limit 3 shows actual CI output (not "should be fine")
-2. If healthy: Beads issue is closed (bd close <id> run and confirmed)
+2. If healthy: Beads issues extracted from PR body/branch and closed (bd close run and confirmed)
+   - If no beads ID found: user was warned and given manual close command
 3. If issues found: Beads tracking issue created for every problem
 4. Worktree removed (or confirmed already gone) — OR Step 6 was intentionally skipped because CI was unhealthy; if skipped, state explicitly: "cleanup deferred, CI was not healthy"
 "It should be fine" is not evidence. Run the command. Show the output.

package/AGENTS.md

@@ -173,3 +173,100 @@ Task 2: Validation logic
 - [docs/VALIDATION.md](docs/VALIDATION.md) - Enforcement and validation details
 
 **Load these files when you need detailed instructions for a specific stage.**
+
+## Descriptive Context Convention
+
+Every stage transition should carry structured context so the next stage (or a new session) can resume without re-reading the full design doc. This convention is **advisory** — warnings are informational, not blocking.
+
+### Required Fields at Each Stage Exit
+
+| Stage Exit | Summary | Decisions | Artifacts | Next |
+|------------|---------|-----------|-----------|------|
+| /plan      | Design approach chosen | Key trade-offs resolved | Design doc, task list paths | First dev task focus |
+| /dev       | Tasks completed, gate count | Spec gaps encountered | Changed files, test files | Validation priorities |
+| /validate  | All checks pass/fail summary | Failures diagnosed | Scripts/commands run | Ship readiness |
+| /ship      | PR created, checks pending | Template sections filled | PR URL, branch name | Review focus areas |
+| /review    | All feedback addressed | Comment resolutions | Fixed files, commit SHAs | Doc update needs |
+| /premerge  | Docs updated, CI green | N/A | Updated doc files | Merge instructions |
+
+### Validation Command
+
+Run at each stage exit to check for missing context:
+
+```bash
+bash scripts/beads-context.sh validate <beads-issue-id>
+```
+
+This checks: (1) issue has a description, (2) at least one stage transition exists, (3) most recent transition has a summary, (4) design metadata is set if past the plan stage. Exits 0 when context checks run (even if warnings are found); exits 1 only if the issue cannot be retrieved.
+
+### Field Definitions
+
+- **Summary**: 1-2 sentence recap of what was accomplished in this stage. Example: `--summary "All 5 tasks done, 1 decision gate fired"`
+- **Decisions**: Key choices made during this stage that affect downstream work. Example: `--decisions "Used streaming parser over DOM for memory efficiency"`
+- **Artifacts**: File paths or URLs produced by this stage. Example: `--artifacts "lib/parser.js test/parser.test.js docs/plans/2026-03-26-parser-design.md"`
+- **Next**: Guidance for the next stage on what to focus on. Example: `--next "Run lint first — streaming approach may trigger no-await rule"`
+
+### Usage in Stage Transitions
+
+```bash
+# Basic (backward compatible)
+bash scripts/beads-context.sh stage-transition <id> dev validate
+
+# With context fields (recommended)
+bash scripts/beads-context.sh stage-transition <id> dev validate \
+  --summary "All 5 tasks done, 0 gates fired" \
+  --decisions "Used approach A per design doc" \
+  --artifacts "lib/foo.js test/foo.test.js" \
+  --next "Run type check and lint"
+```
+
+### Enforcement Level
+
+This convention is **advisory only**. The `validate` subcommand prints warnings but always exits 0. It does not block any stage transition. The goal is to build good habits, not to create friction.
+
+<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->
+## Beads Issue Tracker
+
+This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
+
+### Quick Reference
+
+```bash
+bd ready              # Find available work
+bd show <id>          # View issue details
+bd update <id> --claim  # Claim work
+bd close <id>         # Complete work
+```
+
+### Rules
+
+- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists. Exception: `/plan` Phase 3 generates task lists at `docs/plans/YYYY-MM-DD-<slug>-tasks.md` — these are approved artifacts consumed by `/dev`, but `bd` remains the source of truth for issue state. GitHub issues may be used for external/public tracking; CI may sync GitHub issue lifecycle to Beads (see `docs/BEADS_GITHUB_SYNC.md`).
+- Run `bd prime` for detailed command reference and session close protocol
+- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
+
+## 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
+4. **PUSH TO REMOTE** - This is MANDATORY:
+   ```bash
+   git pull --rebase
+   bd dolt push   # requires Dolt-backed Beads — run 'bd init' if missing
+   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
+<!-- END BEADS INTEGRATION -->

package/CLAUDE.md

@@ -80,6 +80,16 @@ git commit --no-verify           # Skip pre-commit hooks
 
 **⚠️ AI agents must NEVER use `LEFTHOOK=0`, `--no-verify`, or any hook bypass.** If a hook fails, fix the underlying issue. Only humans may bypass hooks in emergencies, documented in the PR description.
 
+**Preferred push workflow** (for AI agents and humans):
+```bash
+forge push              # Runs branch protection + lint + tests, then pushes
+forge push --quick      # Review-cycle: lint-only push (CI runs full suite)
+forge worktree create <slug>  # Creates worktree with Beads integration
+forge test              # Runs tests with correct timeouts + Beads skip
+forge sync              # Syncs Beads data (dolt pull + push)
+forge clean             # Removes merged worktrees (stops Dolt servers)
+```
+
 See [.github/pull_request_template.md](.github/pull_request_template.md) for PR guidelines.
 
 ---

package/README.md

@@ -222,8 +222,8 @@ bunx forge setup --merge=smart    # Intelligent merge
 - Infers project stage (new, active, stable)
 - Saves to `.forge/context.json`
 
-**Workflow Profiles**
-- Adapts workflow based on work type (3-8 stages):
+**Workflow Profiles** *(planned — not yet wired into setup)*
+- Will adapt workflow based on work type (3-8 stages):
   - `critical`: Full 8-stage workflow (auth, payments, security-sensitive)
   - `standard`: 7-stage workflow (typical features)
   - `refactor`: Behavior-preserving 5-stage workflow

package/bin/forge-cmd.js

@@ -223,7 +223,11 @@ async function main() { // NOSONAR S3776
 			const context = {
 				branch,
 				researchDoc: fs.existsSync('docs/research') ? fs.readdirSync('docs/research').find(f => f.endsWith('.md')) : null,
-				plan: fs.existsSync('.claude/plans') ? fs.readdirSync('.claude/plans').find(f => f.endsWith('.md')) : null,
+				plan: (() => {
+					if (!fs.existsSync('docs/plans')) return null;
+					const slug = branch.replace(/^(feat|fix|docs|refactor)\//, '');
+					return fs.readdirSync('docs/plans').find(f => f.endsWith('.md') && f.includes(slug)) || null;
+				})(),
 				tests: (() => { try { return fs.readdirSync('test').filter(f => f.endsWith('.test.js')); } catch (error_) { void error_; return []; } })(), // NOSONAR S2486 - intentional: missing test dir
 			};
 			const stageResult = HANDLERS.status.detectStage(context);

package/bin/forge-preflight.js

@@ -199,8 +199,21 @@ function validateShip() {
   check(
     "Tests pass",
     () => {
+      // Detect package manager from lock files (same heuristic as forge.js)
+      let cmd = "npm";
+      let cmdArgs = ["run", "test"];
+      if (fs.existsSync("bun.lockb") || fs.existsSync("bun.lock")) {
+        cmd = "bun";
+        cmdArgs = ["run", "test"];
+      } else if (fs.existsSync("pnpm-lock.yaml")) {
+        cmd = "pnpm";
+        cmdArgs = ["run", "test"];
+      } else if (fs.existsSync("yarn.lock")) {
+        cmd = "yarn";
+        cmdArgs = ["run", "test"];
+      }
       try {
-        execFileSync("npm", ["test"], { stdio: "pipe" });
+        execFileSync(cmd, cmdArgs, { stdio: "pipe" });
         return true;
       } catch (err) {
         const output = ((err.stdout || "") + "\n" + (err.stderr || "")).trim();
@@ -210,7 +223,7 @@ function validateShip() {
         return false;
       }
     },
-    "Tests are failing. Fix them before shipping: npm test",
+    "Tests are failing. Fix them before shipping.",
   );
 
   check(