forge-workflow 0.0.2 → 0.0.4

package/.claude/commands/dev.md

@@ -63,6 +63,32 @@ Do NOT write any code until ALL confirmed:
 
 ---
 
+
+### Multi-developer conflict check (soft block)
+
+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
+
+# Check for conflicts with the current beads issue
+bash scripts/conflict-detect.sh --issue <beads-id>
+```
+
+If exit code 2 (validation error): show error message, abort — do not show conflict prompt.
+
+If exit code 1 (conflicts found):
+- Display the conflict output to the developer
+- Ask: "Other developers are working in overlapping areas. Proceed anyway? (y/n)"
+- If `n`: exit cleanly, no side effects
+- If `y`: log override via `bd comments add <id> "Conflict override: proceeding despite overlap with <conflicting-issues>"`, then continue to Per-Task Loop
+- Audit: record conflict override per OWASP A09
+
+If exit code 0: proceed silently to Per-Task Loop.
+
+---
+
 ## Per-Task Loop
 
 Repeat for each task in the task list, in order:

package/.claude/commands/plan.md

@@ -20,10 +20,16 @@ Before ANY planning work begins:
    - Tell the user: "You are on '<branch>'. Planning must start from a clean worktree on master.
      Run: git checkout master — then re-run /plan."
 3. If on master, create the worktree NOW before asking any questions:
-   a. git worktree add -b feat/<slug> .worktrees/<slug>
+   a. bd worktree create .worktrees/<slug> --branch feat/<slug>
    b. cd .worktrees/<slug>
 4. Confirm: "Working in isolated worktree: .worktrees/<slug> (branch: feat/<slug>)"
-5. ONLY THEN begin Phase 1.
+5. Create the epic issue and record the stage transition:
+   ```bash
+   bd create --title="<feature-name>" --type=epic
+   bd update <id> --status=in_progress
+   bash scripts/beads-context.sh stage-transition <id> none plan
+   ```
+6. ONLY THEN begin Phase 1.
 
 Rationale: Planning commits (design docs, task lists) belong only to this feature's branch.
 If planning runs in the main directory on a non-master branch, those commits contaminate
@@ -44,10 +50,92 @@ between parallel features or sessions.
 
 ---
 
+
+### Multi-developer conflict check (soft block)
+
+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
+
+# Check for conflicts with this issue's planned work area
+bash scripts/conflict-detect.sh --issue <beads-id>
+```
+
+If exit code 2 (validation error): show error message, abort — do not show conflict prompt.
+
+If exit code 1 (conflicts found):
+- Display the conflict output to the developer
+- Ask: "Other developers are working in overlapping areas. Proceed anyway? (y/n)"
+- If `n`: exit cleanly, no side effects
+- If `y`: log override via `bd comments add <id> "Conflict override: proceeding despite overlap with <conflicting-issues>"`, then continue to Phase 1
+- Audit: record conflict override per OWASP A09
+
+If exit code 0: proceed silently to Phase 1.
+
+---
+
 ## Phase 1: Design Intent (Brainstorming)
 
 **Goal**: Capture WHAT to build — purpose, constraints, success criteria, edge cases, approach.
 
+### Step 0: Dependency ripple check (advisory)
+
+Before exploring context or asking questions, check for potential conflicts with in-flight work:
+
+```bash
+# If a Beads issue ID is known (e.g., from /status or bd ready):
+bash scripts/dep-guard.sh check-ripple <beads-issue-id>
+
+# If no issue exists yet (first-time plan):
+bd list --status=open,in_progress
+```
+
+Review the output. If overlaps are detected:
+- Consider whether the overlapping issue should be a dependency
+- Note any shared areas for the design Q&A
+- This check is **advisory only** — always proceed to Step 1 regardless of findings
+
+#### Ripple Analyst Agent (spawned when contract overlaps found)
+
+When `check-ripple` detects overlapping issues AND contract metadata is available, spawn a Ripple Analyst subagent with this prompt:
+
+**Input to agent**:
+- Current issue's contract changes (from `extract-contracts` output)
+- Consumer code snippets (from `find-consumers` output for each changed contract)
+- Overlapping issue's title, description, and contract metadata
+
+**Agent instructions**:
+1. For each overlapping contract, imagine 2-3 concrete break scenarios:
+   - "If [contract X] changes [specific behavior], then [consumer Y] will [specific failure]"
+2. Rate overall impact as one of:
+   - **NONE**: No real conflict despite keyword overlap
+   - **LOW**: Consumers need trivial adjustment (add parameter, rename call)
+   - **HIGH**: Consumer needs significant rework (parsing logic, data handling changes)
+   - **CRITICAL**: Consumer is in an active in_progress issue's task list
+3. **When uncertain, default to HIGH** — conservative over permissive
+4. Recommend one action:
+   - Add dependency (`bd dep add <source> <target>`)
+   - Coordinate with other issue's developer
+   - Scope down current feature to avoid overlap
+   - Proceed as-is (no real conflict)
+
+**Output format**:
+```
+Impact: [NONE|LOW|HIGH|CRITICAL]
+Confidence: [high|medium|low]
+
+Break scenarios:
+1. [scenario description]
+2. [scenario description]
+
+Recommendation: [action]
+Reason: [why this action]
+```
+
+This agent is advisory only. The developer always makes the final decision.
+
 ### Step 1: Explore project context
 
 Before asking any questions, read relevant files:
@@ -125,6 +213,11 @@ Do NOT begin Phase 2 (web research) until:
 
 **Goal**: Find HOW to build it — best practices, known issues, security risks, TDD scenarios.
 
+Record the phase transition before starting research:
+```bash
+bash scripts/beads-context.sh stage-transition <id> plan research
+```
+
 Run these in parallel:
 
 ### Web research (parallel-deep-research skill)
@@ -215,13 +308,19 @@ Do NOT begin Phase 3 (setup) until:
 
 ## Phase 3: Setup + Task List
 
-**Goal**: Create branch, worktree, Beads issue, and a complete task list ready for /dev.
+**Goal**: Create branch, worktree, and a complete task list ready for /dev.
+
+Record the phase transition before starting setup:
+```bash
+bash scripts/beads-context.sh stage-transition <id> research setup
+```
+
+### Step 1: Link child issues to the epic
 
-### Step 1: Beads issue
+The epic was created in the Entry HARD-GATE (Phase 1 entry). If this feature requires child issues (sub-tasks tracked separately), create them now and link to the epic:
 
 ```bash
-bd create --title="<feature-name>" --type=feature
-bd update <id> --status=in_progress
+bd create --title="<sub-task-name>" --type=feature --parent=<epic-id>
 ```
 
 ### Step 2: Branch + worktree
@@ -239,10 +338,9 @@ else
   # Step 2b: Verify .worktrees/ is gitignored — add if missing
   git check-ignore -v .worktrees/ || echo ".worktrees/" >> .gitignore
 
-  # Step 2c: Create branch + worktree in one command (from master)
-  # Using -b with worktree add avoids "branch already checked out" error
+  # Step 2c: Create a Beads-aware worktree rooted on master
   git checkout master
-  git worktree add -b feat/<slug> .worktrees/<slug>
+  bd worktree create .worktrees/<slug> --branch feat/<slug>
   cd .worktrees/<slug>
 fi
 ```
@@ -315,6 +413,38 @@ bash scripts/beads-context.sh set-acceptance <id> "<success-criteria from design
 
 Both commands must exit with code 0. If either fails, investigate (wrong issue ID? missing script?) before continuing.
 
+### Step 5c: Contract extraction and logic-level dependency review
+
+After saving the task list and Beads context, extract and store contract metadata, then run the logic-level Phase 3 dependency review:
+
+```bash
+# Extract contracts — only call store-contracts if extract succeeds (exit 0)
+if bash scripts/dep-guard.sh extract-contracts docs/plans/YYYY-MM-DD-<slug>-tasks.md > /tmp/contracts.txt; then
+  bash scripts/dep-guard.sh store-contracts <id> "$(cat /tmp/contracts.txt)"
+else
+  echo "No contracts found — skipping store-contracts"
+fi
+
+# Re-run ripple check using Beads JSON + logic-level analysis
+bash scripts/dep-guard.sh check-ripple <id>
+```
+
+`extract-contracts` exits 1 when no contracts are found (not an error — just nothing to store). `store-contracts` must exit 0 if called.
+
+`check-ripple` is now advisory but logic-aware. It should:
+- read Beads issue data via JSON
+- analyze import/call-chain, contract, and behavioral dependency signals
+- show rubric score, confidence, issue pairs, and proposed dependency updates with pros/cons
+- stop for user approval whenever a dependency mutation is proposed
+
+If the user approves a dependency mutation, apply it explicitly:
+
+```bash
+bash scripts/dep-guard.sh apply-decision <id> <dependent-id> <depends-on-id> "<approval rationale>"
+```
+
+That approval step must validate with `bd dep cycles`, show `bd graph`, summarize `bd ready`, and persist the decision via `bd set-state` plus `bd comments`. Beads remains the canonical machine-readable decision record; the plan docs hold only the concise summary.
+
 ### Step 6: User review
 
 Present the full task list. Allow the user to reorder, split, or remove tasks.
@@ -332,6 +462,8 @@ Do NOT proceed to /dev until ALL are confirmed:
 6. User has confirmed task list is correct
 7. `beads-context.sh set-design` ran successfully (exit code 0)
 8. `beads-context.sh set-acceptance` ran successfully (exit code 0)
+9. `dep-guard.sh store-contracts` ran successfully (exit code 0) — or skipped if no contracts found
+10. `dep-guard.sh check-ripple` ran successfully and any proposed dependency mutation was reviewed with the user before calling `apply-decision`
 </HARD-GATE>
 ```
 

package/.claude/commands/premerge.md

@@ -82,9 +82,6 @@ Check each of the following and update if the feature affects it. Be selective
 **F. `AGENTS.md`** (if agent config, skills, or cross-agent workflow changed):
 - Update relevant sections describing agent capabilities or workflow
 
-**G. `docs/WORKFLOW.md`** (if the workflow itself changed):
-- Update stage descriptions or workflow tables
-
 **Commit doc updates to feature branch**:
 
 ```bash

package/.claude/commands/rollback.md

@@ -186,18 +186,18 @@ git commit -m "Rollback: <files>"
 ```bash
 bunx forge rollback
 # Select: 4. Rollback specific files
-# Enter: AGENTS.md,docs/WORKFLOW.md
+# Enter: AGENTS.md,CLAUDE.md
 
 ✓ Validating file paths...
 ✓ Working directory is clean
 ✓ Extracting USER sections...
-✓ Executing: git checkout HEAD~1 -- AGENTS.md docs/WORKFLOW.md
+✓ Executing: git checkout HEAD~1 -- AGENTS.md CLAUDE.md
 ✓ Committing changes...
 ✓ Restoring USER sections...
 ✓ Amended commit to preserve USER content
 
 Rollback complete!
-  Commit: q4r5s6t "Rollback: AGENTS.md, docs/WORKFLOW.md"
+  Commit: q4r5s6t "Rollback: AGENTS.md, CLAUDE.md"
   Files affected: 2
 ```
 
@@ -717,5 +717,5 @@ bunx forge rollback
 
 - [/dev](.claude/commands/dev.md) - TDD development workflow
 - [/validate](.claude/commands/validate.md) - Validation before shipping
-- [docs/WORKFLOW.md](../../docs/WORKFLOW.md) - Complete workflow guide
+- [AGENTS.md](../../AGENTS.md) - Complete workflow guide
 - [Beads](https://github.com/beadshq/beads) - Issue tracking integration

package/.claude/commands/ship.md

@@ -29,60 +29,97 @@ Do NOT create PR until:
 ### Step 1: Verify /validate Passed
 Ensure all four validation checks completed successfully with fresh output in this session.
 
-### Step 2: Update Beads
+### Step 2: Freshness Check — Is Branch Still Current?
+
+Even though /validate rebased onto the base branch, time may have passed since then (user reviewed design doc, took a break, etc.). This lightweight check catches staleness before pushing.
+
+```bash
+BASE=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}')
+if [ -z "$BASE" ] || [ "$BASE" = "(unknown)" ]; then BASE="master"; fi
+git fetch origin "$BASE" || { echo "✗ Fetch failed — cannot verify freshness"; exit 1; }
+BEHIND=$(git rev-list --count HEAD..origin/"$BASE")
+```
+
+- If `BEHIND > 0`: **STOP**. Print: "$BASE has advanced since /validate ($BEHIND new commits). Run /validate again to rebase and re-check."
+- If `BEHIND = 0`: Continue to push.
+- If fetch fails: the `|| { ...; exit 1; }` guard catches this — **STOP**. Do NOT push without confirming freshness.
+
+This is NOT a full rebase — just a check. The rebase happens in /validate where the full test suite runs afterward.
+
+### Step 3: Update Beads
 ```bash
 bd update <id> --status done
 bd sync
 ```
 
-### Step 3: Push Branch
+### Step 4: Push Branch
+
+Use `--force-with-lease` because `/validate` may have rebased the branch, rewriting history. This is safe: it only forces the push if the remote branch hasn't been updated by someone else since the last fetch.
+
 ```bash
-git push -u origin <branch-name>
+git push --force-with-lease -u origin <branch-name>
 ```
 
-### Step 4: Create PR
+### Step 5: Create PR
+
+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.
+
+If no Beads issue exists (hotfix, external contribution), skip the "Closes" line.
 
 ```bash
-gh pr create --title "feat: <feature-name>" --body "$(cat <<'EOF'
-## Summary
-[Auto-generated from commits and design doc]
+gh pr create --title "<type>: <concise description>" --body "$(cat <<'EOF'
+## Problem
+[What was broken, what need existed, or what user pain this addresses]
 
-## Design Doc
-See: docs/plans/YYYY-MM-DD-<slug>-design.md
+## Root Cause
+[Why it happened, why it was missing, or what gap existed]
 
-## Decisions Log
-See: docs/plans/YYYY-MM-DD-<slug>-decisions.md (if any undocumented decisions arose during /dev)
+## Fix
+[What this PR does to solve it — approach, not implementation details]
+
+## Value
+[Who benefits, what improves, what risk is removed]
 
-## Beads Issue
+## Beads
 Closes: <issue-id>
 
-## Key Decisions
-[From design doc - 3-5 key decisions with reasoning]
+<details>
+<summary>Implementation Details</summary>
 
-## TDD Test Coverage
-- Unit tests: [count] tests, [X] scenarios
-- Integration tests: [count] tests
-- E2E tests: [count] tests
-- All tests passing ✓
+### Test Coverage
+- Tests: [count] passing
+- Scenarios covered: [list key scenarios]
 
-## Security Review
-- OWASP Top 10: All mitigations implemented
-- Security tests: [count] scenarios passing
-- Automated scan: No vulnerabilities
+### Security Review
+- OWASP Top 10: [summary — applicable risks and mitigations]
+- Automated scan: [result]
 
-## Test Plan
+### Design Doc
+See: docs/plans/YYYY-MM-DD-<slug>-design.md
+
+### Decisions Log
+See: docs/plans/YYYY-MM-DD-<slug>-decisions.md (if any undocumented decisions arose during /dev)
+
+### Key Decisions
+[From design doc — 3-5 key decisions with reasoning]
+
+### Documentation Updated
+[List docs updated in this PR, or "None — no doc-facing changes"]
+
+### Validation
 - [x] Type check passing
-- [x] Lint passing
-- [x] Code review passing
-- [x] E2E tests passing
+- [x] Lint passing (0 errors, 0 warnings)
+- [x] All tests passing
 - [x] Security review completed
 
+</details>
+
 🤖 Generated with [Claude Code](https://claude.com/claude-code)
 EOF
 )"
 ```
 
-### Step 5: Record Stage Transition
+### Step 6: Record Stage Transition
 ```bash
 bash scripts/beads-context.sh stage-transition <id> ship review
 ```
@@ -91,20 +128,13 @@ bash scripts/beads-context.sh stage-transition <id> ship review
 
 ```
 ✓ Validation: /validate passed (all 4 checks — fresh output confirmed)
+✓ Freshness: Branch is up-to-date with master
 ✓ Beads: Marked done & synced (forge-xyz)
 ✓ Pushed: feat/stripe-billing
 ✓ PR created: https://github.com/.../pull/123
+  - PR body: Problem → Root Cause → Fix → Value (narrative format)
   - Beads linked: forge-xyz
-  - Design doc linked: docs/plans/2026-02-26-stripe-billing-design.md
-  - Decisions log linked: docs/plans/2026-02-26-stripe-billing-decisions.md
-  - Test coverage documented
-  - Security review documented
-
-PR Summary:
-  - 12 commits
-  - 18 test cases, all passing
-  - OWASP Top 10 security review completed
-  - 3 key architectural decisions documented
+  - Implementation details in collapsible section
 
 ⏸️  PR created, awaiting automated checks (Greptile, SonarCloud, GitHub Actions)
 
@@ -126,9 +156,9 @@ Stage 7: /verify     → Post-merge CI check on main
 
 ## Tips
 
-- **Complete PR body**: Include design doc, decisions log, and test coverage
-- **Link everything**: Design doc, decisions log, Beads issue
-- **Document security**: OWASP Top 10 review in PR body
+- **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
 - **Wait for checks**: Let GitHub Actions, Greptile, SonarCloud run
 - **NO auto-merge**: Always wait for /review phase

package/.claude/commands/status.md

@@ -16,60 +16,31 @@ This command helps you understand the current state of the project before starti
 
 ## What This Command Does
 
-### Step 1: Check Project Health
-```bash
-bd stats
-```
-- How many open / in-progress / completed issues?
-- Any blocked issues?
+## Step 0: Sync team state
 
-### Step 2: Check Active Work
 ```bash
-# Active Beads issues
-bd list --status in_progress
+# Sync team state before showing status
+bash scripts/sync-utils.sh auto-sync
 ```
 
-For each in-progress issue, show compact progress:
+### Step 1: Smart Status (ranked issues with conflict detection)
 ```bash
-bash scripts/beads-context.sh parse-progress <issue-id>
+bash scripts/smart-status.sh
 ```
-Display the compact output (e.g., "3/7 tasks done | Last: Validation logic (def5678)")
+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.
 
-Hint: `bd show <id>` for full context on any issue.
+For full context on any issue: `bd show <id>`
 
-### Step 3: Review Recent Work
+### Step 2: Review Recent Commits
 ```bash
-# Recent commits
 git log --oneline -10
-
-# Recently completed Beads
-bd list --status completed --limit 5
 ```
 
-### Step 4: Determine Context
+### Step 3: Determine Context
 - **New feature**: No active work, ready to start fresh
 - **Continuing work**: In-progress issues found, resume where left off
 - **Review needed**: Work marked complete, needs review/merge
 
-## Example Output
-
-```
-✓ Project Health: 3 open, 1 in-progress, 12 completed
-
-Active Work:
-  - forge-ctc: Clean up stale workflow refs (in_progress)
-    3/7 tasks done | Last: Validation logic (def5678)
-    → bd show forge-ctc for full context
-
-Recent Completions:
-  - forge-uto: Sync AGENTS.md with agent cleanup (closed 2 days ago)
-  - forge-abc: Auth refresh tokens (closed 5 days ago)
-
-Context: Continuing work
-
-Next: Resume with /dev or /validate (check issue status)
-```
-
 ## Next Steps
 
 - **If starting new work**: Run `/plan <feature-name>`

package/.claude/commands/validate.md

@@ -2,6 +2,11 @@
 description: Complete validation (type/lint/tests/security)
 ---
 
+> **Note:** Three things share the "validate" name in Forge:
+> - `/validate` (this command): Workflow Stage 3 — rebases onto the base branch, then runs type/lint/test/security checks
+> - `forge-preflight` (formerly forge-validate): CLI tool — checks prerequisites before a stage
+> - `bun run check` (scripts/validate.sh): Local quality gate — runs type/lint/test/security checks only (does NOT rebase; assumes branch is already current with the base branch)
+
 Run comprehensive validation including type checking, linting, code review, security review, and tests.
 
 # Validate
@@ -14,10 +19,50 @@ This command validates all code before creating a pull request.
 /validate
 ```
 
-Or use the unified validation script:
+Or use the validation script (checks only — no rebase):
 
 ```bash
-bun run check    # Runs all validation steps automatically (check is the npm script name; /validate is the workflow command)
+bun run check    # Runs lint/test/security checks only. Does NOT rebase onto the base branch.
+                 # Use /validate for the full workflow (rebase + checks).
+```
+
+```
+<HARD-GATE: /validate entry — rebase onto latest base branch>
+Before running ANY validation checks:
+
+0. Resolve the base branch dynamically (do NOT hardcode master or main):
+   BASE=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}')
+   if [ -z "$BASE" ] || [ "$BASE" = "(unknown)" ]; then BASE="master"; fi
+
+   This handles repos using main, master, or any other default branch.
+   Falls back to "master" when HEAD is unresolved (detached remote, empty repo).
+
+1. Fetch latest base branch:
+   git fetch origin "$BASE" || { echo "✗ Fetch failed — cannot verify branch freshness"; exit 1; }
+
+   The `|| { ...; exit 1; }` guard ensures fetch failures are never silently skipped.
+
+2. Check if branch is behind:
+   BEHIND=$(git rev-list --count HEAD..origin/"$BASE")
+
+3. If BEHIND > 0:
+   a. Run: git rebase origin/"$BASE" || REBASE_FAILED=1
+   b. If rebase succeeds (REBASE_FAILED unset): print "✓ Rebased onto latest $BASE ($BEHIND commits integrated)"
+   c. If rebase fails (REBASE_FAILED=1 — conflicts or any other error):
+      - Capture conflicting files BEFORE aborting: git diff --name-only --diff-filter=U
+      - Run: git rebase --abort
+      - Print the captured conflicting file list
+      - Print: "✗ Rebase conflict — resolve manually, then re-run /validate"
+      - STOP. Do NOT proceed to any validation checks.
+
+4. If BEHIND = 0:
+   Print "✓ Branch is up-to-date with $BASE" and continue.
+
+Rationale: Without this step, validation checks run against stale code that doesn't
+include recent base branch changes. Integration issues are only caught after the PR is
+created, wasting CI cycles and review time. Rebasing here ensures /validate results
+reflect the true state of what will be merged.
+</HARD-GATE>
 ```
 
 ## What This Command Does