forge-workflow 0.0.9 → 0.1.0-beta.2

package/skills/rollback/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: rollback
+description: >
+  Safely revert or undo a change that is already committed or shipped, using non-destructive
+  `git revert` (never `reset --hard`, `push --force`, or `clean`). Drives the interactive
+  `bunx forge rollback` menu: undo the last commit, revert a commit by hash, revert a merged
+  PR (git revert -m 1), restore individual files to a prior version, revert a commit range, or
+  dry-run/preview first. Use when the user says roll back, revert, undo, back out, or restore
+  — e.g. "undo the last commit", "undo that change, the approach was wrong", "back out PR
+  #123", "revert the merge commit", "restore src/auth.js to before my last commit", or when a
+  shipped/merged change broke something and must be pulled back. Do NOT use for: replying to
+  or fixing PR review feedback (review), monitoring an open PR's checks toward merge
+  (shepherd), the post-merge CI health check on master (verify), pushing a branch or opening a
+  PR (ship), or ordinary issue status/field edits (issue-basics).
+allowed-tools: Bash, Read, Edit, Grep, Glob
+---
+
+Comprehensive rollback system with multiple methods and automatic USER content preservation.
+
+# Rollback
+
+This skill provides safe rollback operations with comprehensive validation and USER section preservation.
+
+## Usage
+
+```bash
+bunx forge rollback
+```
+
+Interactive menu with 6 options:
+1. **Rollback last commit** - Quick undo of most recent change
+2. **Rollback specific commit** - Target any commit by hash
+3. **Rollback merged PR** - Revert an entire PR merge
+4. **Rollback specific files** - Restore only certain files
+5. **Rollback entire branch** - Revert multiple commits
+6. **Preview rollback** - Dry run mode (shows changes without executing)
+
+## How It Works
+
+### Safety Features
+
+**1. Working Directory Check**
+- Requires clean working directory (no uncommitted changes)
+- Prevents accidental data loss
+- Prompts to commit or stash changes first
+
+**2. Input Validation**
+- Commit hashes: Must match `/^[0-9a-f]{4,40}$/i` or be 'HEAD'
+- File paths: Validated to be within project (prevents path traversal)
+- Methods: Whitelisted to 'commit', 'pr', 'partial', 'branch'
+- Shell metacharacters: Rejected (`;`, `|`, `&`, `$`, `` ` ``, `(`, `)`, `<`, `>`, `\n`, `\r`)
+
+**3. USER Section Preservation**
+- Automatically extracts USER sections before rollback
+- Restores USER sections after rollback
+- Preserves custom commands in `.claude/commands/custom/`
+- Amends rollback commit to include restored content
+
+**4. Dry Run Mode**
+- Preview affected files without executing
+- Shows what would change
+- No git operations performed
+
+**5. Non-Destructive**
+- Uses `git revert` (creates new commit)
+- Never uses `git reset --hard` (destructive)
+- Preserves full git history
+- Can be undone with another rollback
+
+### USER Section Preservation
+
+**What Gets Preserved**:
+```markdown
+<!-- USER:START -->
+Your custom content here
+<!-- USER:END -->
+
+<!-- USER:START:custom-name -->
+Named USER section
+<!-- USER:END:custom-name -->
+```
+
+**Process**:
+1. Extract all USER sections from AGENTS.md, CLAUDE.md, etc.
+2. Backup custom commands from `.claude/commands/custom/`
+3. Execute rollback operation
+4. Restore USER sections to current file content
+5. Restore custom command files
+6. Amend rollback commit to include restored content
+
+**Result**: Your customizations survive rollback operations.
+
+## Rollback methods
+
+Six methods, selected interactively. Full step-by-step walkthroughs (commands,
+prompts, expected output) are in [references/methods.md](references/methods.md) —
+read it when running a specific rollback.
+
+1. **Rollback last commit** — undo the most recent commit.
+2. **Rollback specific commit** — revert one commit by hash.
+3. **Rollback merged PR** — revert a merge commit.
+4. **Rollback specific files** — restore named files from the previous commit.
+5. **Rollback entire branch** — reset a range.
+6. **Preview (dry run)** — show what a rollback would do, change nothing.
+
+## Integration, issue status & troubleshooting
+
+When to reach for rollback, how it fits the workflow, how revert state is recorded,
+and error recovery are in
+[references/workflow-integration.md](references/workflow-integration.md).

package/skills/rollback/evals/evals.json

@@ -0,0 +1,46 @@
+[
+  {
+    "query": "undo the last commit, the approach was wrong",
+    "should_trigger": true
+  },
+  {
+    "query": "back out PR #482, it's breaking production",
+    "should_trigger": true
+  },
+  {
+    "query": "restore config/database.yml to the version before my last commit",
+    "should_trigger": true
+  },
+  {
+    "query": "show me which files reverting commit a1b2c3d would touch before I actually do it",
+    "should_trigger": true
+  },
+  {
+    "query": "that merged refactor broke everything — revert the whole thing but keep the git history intact",
+    "should_trigger": true
+  },
+  {
+    "query": "what's the safe way to undo a merged pull request?",
+    "should_trigger": true
+  },
+  {
+    "query": "address the Greptile and CodeRabbit comments on my PR",
+    "should_trigger": false
+  },
+  {
+    "query": "keep watching my open PR and tell me when checks pass and it's mergeable",
+    "should_trigger": false
+  },
+  {
+    "query": "master is green after the merge — run the post-merge health check and close the issue",
+    "should_trigger": false
+  },
+  {
+    "query": "push my validated branch and open a pull request",
+    "should_trigger": false
+  },
+  {
+    "query": "set issue forge-9f2 to status review",
+    "should_trigger": false
+  }
+]

package/skills/rollback/references/methods.md

@@ -0,0 +1,204 @@
+# Rollback methods (reference)
+
+Detailed walkthroughs for each rollback method. Read the one you need; the skill body summarizes them.
+
+## Rollback Methods
+
+### 1. Rollback Last Commit
+
+**Use when**: Quick undo of most recent change
+
+**How it works**:
+```bash
+git revert HEAD --no-edit
+```
+
+**Example**:
+```bash
+bunx forge rollback
+# Select: 1. Rollback last commit
+
+✓ Working directory is clean
+✓ Extracting USER sections...
+✓ Executing: git revert HEAD --no-edit
+✓ Restoring USER sections...
+✓ Amended commit to preserve USER content
+
+Rollback complete!
+  Commit: a1b2c3d "Revert: add authentication feature"
+  Files affected: 5
+```
+
+### 2. Rollback Specific Commit
+
+**Use when**: Need to revert a commit from earlier in history
+
+**How it works**:
+```bash
+git revert <commit-hash> --no-edit
+```
+
+**Example**:
+```bash
+bunx forge rollback
+# Select: 2. Rollback specific commit
+# Enter: a1b2c3d
+
+✓ Validating commit hash...
+✓ Working directory is clean
+✓ Extracting USER sections...
+✓ Executing: git revert a1b2c3d --no-edit
+✓ Restoring USER sections...
+✓ Amended commit to preserve USER content
+
+Rollback complete!
+  Commit: x9y8z7w "Revert: a1b2c3d"
+  Files affected: 8
+```
+
+**Input validation**:
+- Accepts 4-40 character hex strings
+- Accepts 'HEAD'
+- Rejects shell metacharacters
+- Rejects invalid formats
+
+### 3. Rollback Merged PR
+
+**Use when**: Need to revert an entire merged pull request
+
+**How it works**:
+```bash
+git revert -m 1 <merge-commit-hash> --no-edit
+```
+
+**Example**:
+```bash
+bunx forge rollback
+# Select: 3. Rollback merged PR
+# Enter: def456 (merge commit hash)
+
+✓ Validating commit hash...
+✓ Working directory is clean
+✓ Extracting USER sections...
+✓ Executing: git revert -m 1 def456 --no-edit
+✓ Restoring USER sections...
+✓ Amended commit to preserve USER content
+✓ Beads integration: Issue #123 marked as 'reverted'
+
+Rollback complete!
+  Commit: m1n2o3p "Revert: Merge pull request #123"
+  Files affected: 15
+  Beads issue: #123 status → reverted
+```
+
+**Beads Integration**:
+- Parses commit message for issue number (`#123`)
+- If found, runs: `forge update <id> --status reverted --comment "PR reverted"`
+- Silently skips if Beads not installed
+- Updates issue tracking automatically
+
+### 4. Rollback Specific Files
+
+**Use when**: Only certain files need to be restored
+
+**How it works**:
+```bash
+git checkout HEAD~1 -- <file1> <file2> ...
+git commit -m "chore: rollback <files>"
+```
+
+**Example**:
+```bash
+bunx forge rollback
+# Select: 4. Rollback specific files
+# Enter: AGENTS.md,CLAUDE.md
+
+✓ Validating file paths...
+✓ Working directory is clean
+✓ Extracting USER sections...
+✓ Executing: git checkout HEAD~1 -- AGENTS.md CLAUDE.md
+✓ Committing changes...
+✓ Restoring USER sections...
+✓ Amended commit to preserve USER content
+
+Rollback complete!
+  Commit: q4r5s6t "chore: rollback AGENTS.md, CLAUDE.md"
+  Files affected: 2
+```
+
+**Path validation**:
+- Comma-separated file paths
+- Validates paths are within project root
+- Prevents path traversal (`../../../etc/passwd`)
+- Rejects shell metacharacters
+- Uses `path.resolve()` + `startsWith()` check
+
+### 5. Rollback Entire Branch
+
+**Use when**: Need to revert a range of commits
+
+**How it works**:
+```bash
+git revert <start-commit>..<end-commit> --no-edit
+```
+
+**Example**:
+```bash
+bunx forge rollback
+# Select: 5. Rollback entire branch
+# Enter: abc123..def456
+
+✓ Validating commit range...
+✓ Working directory is clean
+✓ Extracting USER sections...
+✓ Executing: git revert abc123..def456 --no-edit
+✓ Restoring USER sections...
+✓ Amended commit to preserve USER content
+
+Rollback complete!
+  Commits reverted: 7
+  Files affected: 24
+```
+
+**Range validation**:
+- Format: `start..end`
+- Both commits must be valid hashes (4-40 chars)
+- Rejects invalid formats
+- Checks for `..` separator
+
+### 6. Preview Rollback (Dry Run)
+
+**Use when**: Want to see what would change without executing
+
+**How it works**:
+- Prompts for method and target
+- Validates inputs
+- Shows affected files
+- No git operations performed
+
+**Example**:
+```bash
+bunx forge rollback
+# Select: 6. Preview rollback (dry run)
+# Enter method: partial
+# Enter target: AGENTS.md,package.json
+
+✓ Validating inputs...
+✓ DRY RUN MODE - No changes will be made
+
+Preview of rollback:
+  Method: partial
+  Target: AGENTS.md, package.json
+
+  Files that would be affected:
+    - AGENTS.md
+    - package.json
+
+  USER sections that would be preserved:
+    - AGENTS.md: 2 sections
+
+  Custom commands that would be preserved:
+    - .claude/commands/custom/my-workflow.md
+
+No changes made (dry run).
+```

package/{.cursor/commands/rollback.md → skills/rollback/references/workflow-integration.md}

@@ -1,279 +1,4 @@
-
-Comprehensive rollback system with multiple methods and automatic USER content preservation.
-
-# Rollback
-
-This command provides safe rollback operations with comprehensive validation and USER section preservation.
-
-## Usage
-
-```bash
-bunx forge rollback
-```
-
-Interactive menu with 6 options:
-1. **Rollback last commit** - Quick undo of most recent change
-2. **Rollback specific commit** - Target any commit by hash
-3. **Rollback merged PR** - Revert an entire PR merge
-4. **Rollback specific files** - Restore only certain files
-5. **Rollback entire branch** - Revert multiple commits
-6. **Preview rollback** - Dry run mode (shows changes without executing)
-
-## How It Works
-
-### Safety Features
-
-**1. Working Directory Check**
-- Requires clean working directory (no uncommitted changes)
-- Prevents accidental data loss
-- Prompts to commit or stash changes first
-
-**2. Input Validation**
-- Commit hashes: Must match `/^[0-9a-f]{4,40}$/i` or be 'HEAD'
-- File paths: Validated to be within project (prevents path traversal)
-- Methods: Whitelisted to 'commit', 'pr', 'partial', 'branch'
-- Shell metacharacters: Rejected (`;`, `|`, `&`, `$`, `` ` ``, `(`, `)`, `<`, `>`, `\n`, `\r`)
-
-**3. USER Section Preservation**
-- Automatically extracts USER sections before rollback
-- Restores USER sections after rollback
-- Preserves custom commands in `.claude/commands/custom/`
-- Amends rollback commit to include restored content
-
-**4. Dry Run Mode**
-- Preview affected files without executing
-- Shows what would change
-- No git operations performed
-
-**5. Non-Destructive**
-- Uses `git revert` (creates new commit)
-- Never uses `git reset --hard` (destructive)
-- Preserves full git history
-- Can be undone with another rollback
-
-### USER Section Preservation
-
-**What Gets Preserved**:
-```markdown
-<!-- USER:START -->
-Your custom content here
-<!-- USER:END -->
-
-<!-- USER:START:custom-name -->
-Named USER section
-<!-- USER:END:custom-name -->
-```
-
-**Process**:
-1. Extract all USER sections from AGENTS.md, CLAUDE.md, etc.
-2. Backup custom commands from `.claude/commands/custom/`
-3. Execute rollback operation
-4. Restore USER sections to current file content
-5. Restore custom command files
-6. Amend rollback commit to include restored content
-
-**Result**: Your customizations survive rollback operations.
-
-## Rollback Methods
-
-### 1. Rollback Last Commit
-
-**Use when**: Quick undo of most recent change
-
-**How it works**:
-```bash
-git revert HEAD --no-edit
-```
-
-**Example**:
-```bash
-bunx forge rollback
-# Select: 1. Rollback last commit
-
-✓ Working directory is clean
-✓ Extracting USER sections...
-✓ Executing: git revert HEAD --no-edit
-✓ Restoring USER sections...
-✓ Amended commit to preserve USER content
-
-Rollback complete!
-  Commit: a1b2c3d "Revert: add authentication feature"
-  Files affected: 5
-```
-
-### 2. Rollback Specific Commit
-
-**Use when**: Need to revert a commit from earlier in history
-
-**How it works**:
-```bash
-git revert <commit-hash> --no-edit
-```
-
-**Example**:
-```bash
-bunx forge rollback
-# Select: 2. Rollback specific commit
-# Enter: a1b2c3d
-
-✓ Validating commit hash...
-✓ Working directory is clean
-✓ Extracting USER sections...
-✓ Executing: git revert a1b2c3d --no-edit
-✓ Restoring USER sections...
-✓ Amended commit to preserve USER content
-
-Rollback complete!
-  Commit: x9y8z7w "Revert: a1b2c3d"
-  Files affected: 8
-```
-
-**Input validation**:
-- Accepts 4-40 character hex strings
-- Accepts 'HEAD'
-- Rejects shell metacharacters
-- Rejects invalid formats
-
-### 3. Rollback Merged PR
-
-**Use when**: Need to revert an entire merged pull request
-
-**How it works**:
-```bash
-git revert -m 1 <merge-commit-hash> --no-edit
-```
-
-**Example**:
-```bash
-bunx forge rollback
-# Select: 3. Rollback merged PR
-# Enter: def456 (merge commit hash)
-
-✓ Validating commit hash...
-✓ Working directory is clean
-✓ Extracting USER sections...
-✓ Executing: git revert -m 1 def456 --no-edit
-✓ Restoring USER sections...
-✓ Amended commit to preserve USER content
-✓ Beads integration: Issue #123 marked as 'reverted'
-
-Rollback complete!
-  Commit: m1n2o3p "Revert: Merge pull request #123"
-  Files affected: 15
-  Beads issue: #123 status → reverted
-```
-
-**Beads Integration**:
-- Parses commit message for issue number (`#123`)
-- If found, runs: `bd update <id> --status reverted --comment "PR reverted"`
-- Silently skips if Beads not installed
-- Updates issue tracking automatically
-
-### 4. Rollback Specific Files
-
-**Use when**: Only certain files need to be restored
-
-**How it works**:
-```bash
-git checkout HEAD~1 -- <file1> <file2> ...
-git commit -m "Rollback: <files>"
-```
-
-**Example**:
-```bash
-bunx forge rollback
-# Select: 4. Rollback specific files
-# Enter: AGENTS.md,CLAUDE.md
-
-✓ Validating file paths...
-✓ Working directory is clean
-✓ Extracting USER sections...
-✓ 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, CLAUDE.md"
-  Files affected: 2
-```
-
-**Path validation**:
-- Comma-separated file paths
-- Validates paths are within project root
-- Prevents path traversal (`../../../etc/passwd`)
-- Rejects shell metacharacters
-- Uses `path.resolve()` + `startsWith()` check
-
-### 5. Rollback Entire Branch
-
-**Use when**: Need to revert a range of commits
-
-**How it works**:
-```bash
-git revert <start-commit>..<end-commit> --no-edit
-```
-
-**Example**:
-```bash
-bunx forge rollback
-# Select: 5. Rollback entire branch
-# Enter: abc123..def456
-
-✓ Validating commit range...
-✓ Working directory is clean
-✓ Extracting USER sections...
-✓ Executing: git revert abc123..def456 --no-edit
-✓ Restoring USER sections...
-✓ Amended commit to preserve USER content
-
-Rollback complete!
-  Commits reverted: 7
-  Files affected: 24
-```
-
-**Range validation**:
-- Format: `start..end`
-- Both commits must be valid hashes (4-40 chars)
-- Rejects invalid formats
-- Checks for `..` separator
-
-### 6. Preview Rollback (Dry Run)
-
-**Use when**: Want to see what would change without executing
-
-**How it works**:
-- Prompts for method and target
-- Validates inputs
-- Shows affected files
-- No git operations performed
-
-**Example**:
-```bash
-bunx forge rollback
-# Select: 6. Preview rollback (dry run)
-# Enter method: partial
-# Enter target: AGENTS.md,package.json
-
-✓ Validating inputs...
-✓ DRY RUN MODE - No changes will be made
-
-Preview of rollback:
-  Method: partial
-  Target: AGENTS.md, package.json
-
-  Files that would be affected:
-    - AGENTS.md
-    - package.json
-
-  USER sections that would be preserved:
-    - AGENTS.md: 2 sections
-
-  Custom commands that would be preserved:
-    - .claude/commands/custom/my-workflow.md
-
-No changes made (dry run).
-```
+# Rollback: workflow integration, issue status & troubleshooting (reference)
 
 ## Integration with Workflow
 
@@ -289,13 +14,13 @@ No changes made (dry run).
 - CI/CD failures indicate architecture problems
 - Breaking changes need to be reverted
 
-**After Merging** (`/premerge` + user merge):
+**After Merging** (pre-merge gate + user merge):
 - Production issues discovered
 - Need to revert feature entirely
 - Rollback PR merge commit
 
 **Recovery Scenarios**:
-- Accidentally committed sensitive data (rollback + force push)
+- Accidentally committed sensitive data (follow the secret-removal runbook; rollback alone does not purge history)
 - Merge conflict resolution went wrong
 - Refactor broke existing functionality
 
@@ -303,7 +28,7 @@ No changes made (dry run).
 
 ```bash
 # Standard workflow
-/status → /plan → /dev → /validate → /ship → /review → /premerge → /verify
+/status → /plan → /dev → /validate → /ship → /review → /verify   (pre-merge doc gate runs inside /ship and /review)
 
 # Recovery workflow
 /dev → (issues discovered) → bunx forge rollback → /dev (retry)
@@ -340,7 +65,7 @@ bunx forge rollback
 
 ## Beads Integration
 
-If Beads is installed (`bun install -g @beads/bd`), rollback automatically updates issue tracking.
+If Beads is installed (`bunx forge setup`), rollback automatically updates issue tracking.
 
 ### PR Rollback → Issue Status
 
@@ -348,7 +73,7 @@ When rolling back a merged PR:
 1. Parse commit message for issue number (`#123`, `fixes #456`, etc.)
 2. If issue number found:
    ```bash
-   bd update <id> --status reverted --comment "PR reverted by rollback"
+   forge update <id> --status reverted --comment "PR reverted by rollback"
    ```
 3. Silently skip if:
    - Beads not installed
@@ -360,7 +85,7 @@ When rolling back a merged PR:
 If automatic detection doesn't work:
 ```bash
 # After rollback
-bd update 123 --status reverted --comment "Rolled back due to production issues"
+forge update 123 --status reverted --comment "Rolled back due to production issues"
 ```
 
 ## Troubleshooting
@@ -525,7 +250,8 @@ if (target !== 'HEAD' && !/^[0-9a-f]{4,40}$/i.test(target)) {
 **File paths**:
 ```javascript
 const resolved = path.resolve(projectRoot, file);
-if (!resolved.startsWith(projectRoot)) {
+const rel = path.relative(projectRoot, resolved);
+if (rel.startsWith('..') || path.isAbsolute(rel)) {
   return { valid: false, error: 'Path outside project' };
 }
 ```
@@ -633,7 +359,7 @@ bunx forge rollback
 # ✓ Beads: Issue #123 → status: reverted
 # ✓ Rollback complete!
 
-bd show 123
+forge show 123
 # ID: 123
 # Title: Add real-time updates
 # Status: reverted