forge-workflow 0.0.9 → 0.1.0-beta.2

package/docs/BEADS_GITHUB_SYNC.md

@@ -1,255 +0,0 @@
-# GitHub <-> Beads Issue Sync
-
-Automatic synchronization between GitHub Issues and Beads issue tracking.
-
-**GitHub Issues** = human/team/public interface.
-**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
-
-### Phase 1: GitHub -> Beads (CI-driven)
-
-```mermaid
-sequenceDiagram
-    participant U as User
-    participant GH as GitHub Issues
-    participant WF as GitHub Actions
-    participant BD as Beads CLI
-    participant Repo as .beads/ + mapping
-
-    U->>GH: Opens issue #42
-    GH->>WF: issues.opened trigger
-    WF->>WF: Guard checks (bot? skip label? no-beads?)
-    WF->>WF: Idempotency check (existing bot comment?)
-    WF->>BD: bd create --title "..." --type bug --priority 1
-    BD->>Repo: Write .beads/issues.jsonl
-    WF->>Repo: Write .github/beads-mapping.json {"42": "forge-abc"}
-    WF->>GH: Post bot comment <!-- beads-sync:42 -->
-    WF->>Repo: git commit + push
-
-    U->>GH: Closes issue #42
-    GH->>WF: issues.closed trigger
-    WF->>Repo: Read mapping: "42" -> "forge-abc"
-    WF->>BD: bd close forge-abc --reason "Closed via GitHub #42"
-    WF->>Repo: git commit + push
-```
-
-### Phase 2: Beads -> GitHub (push-triggered)
-
-```mermaid
-sequenceDiagram
-    participant AI as AI Agent
-    participant BD as Beads CLI
-    participant Repo as .beads/
-    participant WF as GitHub Actions
-    participant GH as GitHub Issues
-
-    AI->>BD: forge close forge-abc
-    BD->>Repo: Update issues.jsonl
-    AI->>Repo: git push
-    Repo->>WF: push trigger (paths: .beads/**)
-    WF->>WF: Guard: skip if commit msg starts with "chore(beads):"
-    WF->>Repo: Diff issues.jsonl for closed transitions
-    WF->>GH: gh api PATCH /issues/42 state=closed
-```
-
-### Loop Prevention
-
-Three guards prevent infinite ping-pong:
-
-1. **Bot detection** -- workflows skip events from `github-actions[bot]`
-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
-
----
-
-## Setup
-
-### Via Forge Setup (recommended)
-
-```bash
-bunx forge setup
-# During interactive prompts:
-# "Enable GitHub <-> Beads sync? (y/n)" -> y
-```
-
-This scaffolds:
-- `.github/workflows/github-to-beads.yml`
-- `.github/workflows/beads-to-github.yml` (Phase 2)
-- `.github/beads-mapping.json`
-- `scripts/github-beads-sync/` (Node modules)
-- `scripts/github-beads-sync.config.json`
-
-### Manual Setup
-
-1. Copy workflow files from `templates/` into `.github/workflows/`
-2. Copy `scripts/github-beads-sync/` and `scripts/github-beads-sync.config.json`
-3. Create `.github/beads-mapping.json` with `{}`
-4. Ensure Beads is initialized: `bd init`
-5. Commit and push to enable the workflows
-
----
-
-## Configuration Reference
-
-All settings live in `scripts/github-beads-sync.config.json`.
-
-### Label and Type Mapping
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `labelToType` | `object` | `{"bug":"bug", "enhancement":"feature", "documentation":"task", "question":"task"}` | Maps GitHub labels to Beads issue types. First matching label wins. |
-| `labelToPriority` | `object` | `{"P0":0, "critical":0, "P1":1, "high":1, "P2":2, "medium":2, "P3":3, "low":3, "P4":4, "backlog":4}` | Maps GitHub labels to Beads priority levels (0-4). First matching label wins. |
-| `defaultType` | `string` | `"task"` | Beads type when no label matches `labelToType`. |
-| `defaultPriority` | `number` | `2` | Beads priority when no label matches `labelToPriority`. |
-| `mapAssignee` | `boolean` | `true` | Whether to copy GitHub assignee to Beads issue on creation. |
-
-### Security Gates (Public Repos)
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `publicRepoGate` | `string` | `"none"` | Access control for public repos. See [Security](#security) section. |
-| `gateLabelName` | `string` | `"beads-track"` | Required label when `publicRepoGate` is `"label"`. |
-| `gateAssociations` | `string[]` | `["MEMBER", "COLLABORATOR", "OWNER"]` | Allowed author associations when `publicRepoGate` is `"author_association"`. |
-
-### Example: Custom Configuration
-
-```json
-{
-  "labelToType": {
-    "bug": "bug",
-    "feature": "feature",
-    "chore": "chore",
-    "spike": "task"
-  },
-  "labelToPriority": {
-    "urgent": 0,
-    "important": 1,
-    "normal": 2,
-    "nice-to-have": 3
-  },
-  "defaultType": "task",
-  "defaultPriority": 2,
-  "mapAssignee": true,
-  "publicRepoGate": "author_association",
-  "gateAssociations": ["MEMBER", "COLLABORATOR", "OWNER"]
-}
-```
-
----
-
-## Security
-
-### Public Repo Gate
-
-On public repos, anyone can open an issue -- which triggers a commit to your default branch via the sync workflow. The `publicRepoGate` setting controls who can trigger sync:
-
-| Value | Behavior | Recommended For |
-|-------|----------|-----------------|
-| `"none"` | All issues sync (default). | Private repos, trusted teams. |
-| `"author_association"` | Only issues from authors in `gateAssociations` sync. | Public repos with known contributors. |
-| `"label"` | Only issues with the `gateLabelName` label sync. A maintainer must add the label. | Public repos accepting external issues. |
-
-### Input Sanitization
-
-- Issue titles and bodies are **never interpolated in shell commands**. The sync scripts use Node `execFile` with array arguments (no shell).
-- Workflow files pass event data via `env:` blocks, never via `${{ }}` in `run:` blocks (prevents GitHub Actions injection).
-- Only title, URL, mapped type, and priority are stored in Beads -- raw issue body is not committed.
-
-### SHA-Pinned Actions
-
-All third-party actions in the workflow files are pinned to full commit SHAs, not tags. This prevents supply-chain attacks via tag mutation.
-
-```yaml
-# Good: SHA-pinned
-- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.1.1
-
-# Bad: tag-only (never used)
-- uses: actions/checkout@v4
-```
-
----
-
-## Opt-Out
-
-Two ways to prevent an issue from syncing:
-
-1. **Label**: Add `skip-beads-sync` to the GitHub issue. The workflow checks labels before processing.
-2. **Body keyword**: Include `no-beads` anywhere in the issue body. Useful for quick one-off exclusions.
-
-Both are checked at the `issues.opened` trigger. If added after creation, they prevent close-sync but not the already-created Beads issue.
-
----
-
-## Troubleshooting
-
-### Sync not triggering
-
-- **Check workflow is enabled**: Go to Actions tab in GitHub, verify `github-to-beads` workflow exists and is active.
-- **Check branch**: Workflows must exist on the default branch (usually `main` or `master`).
-- **Check permissions**: The workflow needs `contents: write` and `issues: write` permissions.
-
-### Duplicate Beads issues
-
-- The workflow checks for an existing `<!-- beads-sync:N -->` bot comment before creating. If the comment was deleted, a duplicate may be created.
-- Fix: Check `.github/beads-mapping.json` for the existing mapping and manually remove the duplicate Beads issue with `bd delete`.
-
-### Loop detection firing incorrectly
-
-- If legitimate commits starting with `chore(beads):` are being skipped by the Phase 2 workflow, rename the commit prefix in the workflow file.
-- The bot-actor check uses `github.actor` -- ensure your CI bot user matches the expected name.
-
-### Mapping file conflicts
-
-- If two issues are created simultaneously, the `git push` for the second may fail due to a stale mapping file.
-- The workflow retries with `git pull --rebase` up to 3 times. If it still fails, the workflow run will show as failed -- re-run it manually.
-
-### `bd` command not found in CI
-
-- The workflow installs Beads fresh each run: `bun add -g @beads/bd`.
-- If this fails, check that the workflow uses a runner with Node/Bun available.
-
----
-
-## Fork Behavior
-
-Sync does **not** work in forks. The `GITHUB_TOKEN` provided to forked repo workflows is scoped to the fork and cannot write to the upstream repo's `.beads/` directory or post comments on upstream issues.
-
-When a fork PR uses `Closes #N`, GitHub closes the issue on the **upstream** repo on merge. This triggers the upstream's `issues.closed` workflow, which handles the Beads close normally.
-
----
-
-## GitHub Projects Integration
-
-This plugin creates well-labeled GitHub issues but does **not** manage GitHub Projects boards. Use GitHub's built-in automation instead:
-
-### Setting Up Auto-Add to Project
-
-1. Go to your GitHub Project (Projects tab on your profile or org)
-2. Click the `...` menu, then **Workflows**
-3. Enable **"Auto-add to project"**
-4. Set the filter, for example: `is:issue is:open label:bug,enhancement`
-5. All matching issues (including those created by the sync) will auto-appear on your board
-
-### Recommended Project Views
-
-- **Board view**: Columns for `Open`, `In Progress`, `Done` -- map to Beads statuses
-- **Table view**: Add `Labels`, `Assignees`, `Priority` fields for triage
-- **Filter by label**: Use the labels mapped in your config to create focused views
-
-This approach is more flexible than automating board placement -- you control the filters and views entirely within GitHub's UI.
-
----
-
-## Related Documentation
-
-- [Design doc](plans/2026-03-21-github-beads-sync-design.md) -- full design decisions, OWASP analysis, and edge cases
-- [Toolchain reference](TOOLCHAIN.md) -- Beads CLI commands, installation, and troubleshooting

package/docs/GREPTILE_SETUP.md

@@ -1,400 +0,0 @@
-# Greptile Code Review - Branch Protection Setup
-
-**✅ Greptile is already working on your repository!**
-
-Greptile provides AI-powered code review as a **GitHub App** that automatically analyzes every PR.
-
----
-
-## Current Status
-
-🎉 **Greptile is Fully Operational!**
-
-Your repository has both Greptile features working:
-- ✅ **Greptile Review** (GitHub App) - Provides detailed code review comments
-- ✅ **Greptile Quality Gate** (Workflow) - Enforces minimum score of 4.0/5 before merge
-- ✅ Both integrated into branch protection for master branch
-
----
-
-## Branch Protection Status
-
-### ✅ Fully Configured!
-
-Branch protection for `master` now requires:
-
-1. **Greptile Review** (GitHub App check) - Must pass
-2. **Greptile Quality Gate (≥4/5)** (Custom workflow) - Must pass with score ≥ 4.0
-3. **Other Required Checks**: ESLint, CodeQL, dependency-review
-4. **PR Reviews**: At least 1 approving review required
-5. **Conversation Resolution**: All review threads must be resolved
-
-**Result**: PRs cannot be merged unless:
-- Greptile Review completes successfully
-- Greptile confidence score is at least 4.0/5
-- All other quality checks pass
-- Code has been reviewed and approved
-
----
-
-## How Greptile Works
-
-### GitHub App Integration
-
-- **Automatic**: Runs on every PR (no manual trigger needed)
-- **No Workflow Needed**: Works as a GitHub App, not a GitHub Action
-- **No API Key Required**: Authorized through GitHub App installation
-
-### Review Process
-
-```
-PR created/updated
-    ↓
-Greptile automatically analyzes code
-    ↓
-Posts detailed feedback as comments
-    ↓
-Updates "Greptile Review" check status
-    ↓
-Pass: ✅ Can merge
-Fail: ❌ Blocked (if required in branch protection)
-```
-
-### What Greptile Checks
-
-- 🐛 **Bugs & Edge Cases**: Potential runtime errors, null pointers, race conditions
-- 🔒 **Security**: Vulnerabilities, injection risks, auth issues
-- 📊 **Code Quality**: Complexity, duplication, naming conventions
-- ⚡ **Performance**: Inefficient algorithms, memory leaks
-- 📝 **Best Practices**: Error handling, type safety, modern patterns
-- 🧪 **Testing**: Missing test coverage, test quality
-
----
-
-## Understanding Greptile Feedback
-
-### Confidence Score
-
-Greptile provides a confidence score (0-5) in the PR description that reflects overall code quality:
-
-📊 **Confidence Score Format**: "Confidence Score: X/5" or "Confidence Score: X out of 5"
-🎯 **Quality Gate Threshold**: Minimum 4.0/5 required to merge
-✅ **Detailed inline comments** on specific lines of code
-✅ **Issue severity** indicators (critical, major, minor)
-✅ **Actionable suggestions** with example fixes
-
-### Example from Your PR #13
-
-Greptile identified and you fixed:
-- ✅ Windows path validation bug
-- ✅ Duplicate function definitions
-- ✅ Incorrect fetch timeout implementation
-- ✅ Security vulnerabilities (command injection)
-- ✅ JSON parse crash issues
-- ✅ Unused variables
-
-**Result**: 16/16 issues addressed! 🎉
-
----
-
-## Addressing Greptile Feedback
-
-### Workflow
-
-1. **Read Comments**
-   - Greptile posts inline comments on changed files
-   - Each explains the issue and suggests fixes
-
-2. **Fix Issues**
-   ```bash
-   # Make changes based on feedback
-   git add .
-   git commit -m "fix: address Greptile feedback"
-   git push
-   ```
-
-3. **Auto Re-analysis**
-   - Greptile automatically reviews again after push
-   - Verifies fixes
-   - Updates check status
-
-4. **Resolve Conversations**
-   - Click "Resolve conversation" on each fixed comment
-   - Helps track progress
-
----
-
-## Branch Protection Behavior
-
-### When "Greptile Review" is Required:
-
-```
-✅ All issues addressed          → Check: SUCCESS → ✅ Can merge
-❌ Outstanding issues            → Check: PENDING → ❌ Blocked
-🔄 Analysis in progress          → Check: PENDING → ❌ Blocked
-```
-
-### Emergency Override
-
-If you **must** merge despite Greptile feedback:
-
-1. **Get approval** from tech lead/architect
-2. **Document in PR description**:
-   ```markdown
-   **Emergency Bypass**: Production hotfix for [critical-issue]
-   **Greptile Status**: Bypassed
-   **Justification**: [detailed reason]
-   **Follow-up**: Issue #123 created to address feedback
-   ```
-3. **Temporarily disable branch protection** (admin only)
-4. **Merge**
-5. **Re-enable protection immediately**
-6. **Create follow-up issue** to address Greptile feedback
-
----
-
-## Configuration
-
-### No Setup Required! ✅
-
-Since Greptile is a GitHub App:
-
-- ❌ No API keys needed in secrets
-- ❌ No workflow files needed
-- ❌ No manual configuration
-
-It just works automatically!
-
-### Managing the GitHub App
-
-**View installed apps**:
-```
-https://github.com/settings/installations
-```
-
-**Repository-specific settings** (admin only):
-```
-https://github.com/harshanandak/forge/settings/installations
-```
-
-You can:
-- Enable/disable Greptile for specific repos
-- Adjust review frequency
-- Configure notification settings
-
----
-
-## Customization (Optional)
-
-### Repository Configuration
-
-Create `.greptile/config.yml` in repo root:
-
-```yaml
-# Greptile configuration
-review:
-  # File patterns to ignore
-  exclude:
-    - "*.md"
-    - "test/**"
-    - "docs/**"
-    - "*.test.js"
-    - "dist/**"
-
-  # Focus areas (prioritize these checks)
-  focus:
-    - security
-    - bugs
-    - performance
-
-  # Review depth
-  depth: thorough  # quick, normal, thorough
-```
-
-### Per-PR Instructions
-
-Add comments in PR description to guide Greptile:
-
-```markdown
-@greptile focus on security and performance
-@greptile ignore docs/ and test files
-@greptile be extra strict on src/auth/
-```
-
----
-
-## Troubleshooting
-
-### "Greptile Review check not appearing in branch protection"
-
-**Cause**: Check hasn't completed at least once on any PR.
-
-**Fix**:
-1. It's currently running on PR #13
-2. Wait for it to complete
-3. Then refresh branch protection settings page
-4. "Greptile Review" should now appear in the list
-
-### "Greptile didn't review my PR"
-
-**Possible causes**:
-- GitHub App not installed or disabled
-- PR is a draft (some apps skip drafts)
-- Repository not in allowed list
-
-**Fix**:
-1. Visit: https://github.com/harshanandak/forge/settings/installations
-2. Verify Greptile is installed and enabled
-3. Check repository access permissions
-4. Convert draft to ready for review if applicable
-
-### "How do I request a re-review?"
-
-**Methods**:
-1. **Push new commit** - Triggers automatic re-analysis
-2. **Comment on PR**: `@greptile please review` or `@greptile recheck`
-3. **Close and reopen PR** - Forces fresh analysis
-
-### "Can I see why Greptile flagged something?"
-
-**Yes!**
-1. Go to "Files changed" tab in PR
-2. Find Greptile's comment thread
-3. Each comment explains:
-   - What the issue is
-   - Why it's problematic
-   - How to fix it
-   - Often includes code examples
-
----
-
-## Best Practices
-
-### 1. Address Feedback Incrementally
-
-Don't batch all fixes into one commit:
-- Fix issues as you see them
-- Commit after each logical fix
-- Easier to review and debug
-
-### 2. Use as Learning Tool
-
-Greptile explains *why* something is an issue:
-- Read the explanations, don't just apply fixes blindly
-- Share interesting findings with your team
-- Update coding standards based on patterns
-
-### 3. Combine with Human Review
-
-| Review Type | What It Catches |
-|-------------|-----------------|
-| 🤖 Greptile | Technical bugs, security, complexity, patterns |
-| 👥 Human    | Business logic, UX, architecture, context |
-
-**Both are essential!** They catch different types of issues.
-
-### 4. Don't Fight the AI Unnecessarily
-
-If Greptile flags something:
-- There's usually a valid reason
-- Read the explanation carefully
-- If you disagree, comment why (helps improve Greptile)
-- Propose alternative if you have a better approach
-
-### 5. Track Common Patterns
-
-Notice recurring issues across PRs?
-- Document in coding standards
-- Add to .greptile/config.yml to auto-enforce
-- Share with team in README or CONTRIBUTING.md
-- Consider pre-commit hooks for common issues
-
----
-
-## Verification Checklist
-
-Use this to confirm Greptile is set up correctly:
-
-```
-✅ Greptile GitHub App is installed
-✅ Greptile has access to your repository
-✅ "Greptile Review" check runs on PRs
-✅ Greptile posts code review comments
-✅ "Greptile Review" appears in branch protection options
-✅ "Greptile Review" is selected as required check
-✅ Branch protection rule is saved
-✅ Test: Create PR → Greptile reviews → Merge blocked if issues
-```
-
----
-
-## FAQ
-
-**Q: Does Greptile use a scoring system (like 4.0/5.0)?**
-A: Yes! Greptile Review provides a confidence score (0-5) in the PR description. Our custom Quality Gate workflow enforces a minimum score of 4.0/5 before allowing merges.
-
-**Q: Will it review every single commit?**
-A: It reviews at the PR level. Runs when PR is opened and when new commits are pushed.
-
-**Q: Does it slow down development?**
-A: No! Reviews typically complete in 1-2 minutes. Runs in parallel with other checks.
-
-**Q: Can I disable it for specific PRs?**
-A: Yes, via PR description: `@greptile skip` (but only if not required in branch protection)
-
-**Q: Is it free?**
-A: Greptile has free and paid tiers. Check https://greptile.com/pricing for current plans.
-
-**Q: Does it replace code review?**
-A: No! It augments human review by catching technical issues, allowing humans to focus on architecture, business logic, and UX.
-
-**Q: What languages does it support?**
-A: Most modern languages including JavaScript, TypeScript, Python, Go, Java, Rust, etc.
-
-**Q: Can I customize what it checks for?**
-A: Yes, via `.greptile/config.yml` configuration file.
-
----
-
-## Next Steps
-
-1. ✅ **DONE** - Greptile Review is active and running
-2. ✅ **DONE** - Greptile Quality Gate (≥4/5) is enforced in branch protection
-3. ✅ **DONE** - All required checks configured for master branch
-4. 🎯 **Create new PRs** and watch the quality gate in action
-5. 📚 **Document** your team's policy for handling Greptile feedback
-6. 🎉 **Celebrate** improved code quality!
-
----
-
-## Additional Resources
-
-- **Greptile Documentation**: https://docs.greptile.com
-- **GitHub App Settings**: https://github.com/settings/installations
-- **Branch Protection Guide**: [../.github/BRANCH_PROTECTION_GUIDE.md](../.github/BRANCH_PROTECTION_GUIDE.md)
-- **Your PRs**: Check the [pull requests page](https://github.com/harshanandak/forge/pulls) for examples
-
----
-
-## Summary
-
-**What Greptile Is:**
-- ✅ GitHub App providing detailed code reviews
-- ✅ Custom Quality Gate workflow enforcing minimum score 4.0/5
-- ✅ AI-powered code analysis on every PR
-- ✅ Detailed, actionable feedback with confidence scores
-
-**What's Now Active:**
-- ✅ Greptile Review (GitHub App) is installed and running
-- ✅ Greptile Quality Gate (≥4/5) is enforced in branch protection
-- ✅ PRs to master require score ≥ 4.0/5 to merge
-- ✅ All review comments must be resolved before merge
-
-**Result:**
-- 🚀 Higher code quality with enforced standards
-- 🐛 Fewer bugs in production
-- 📊 Objective quality metrics (4.0/5 minimum)
-- 🛡️ Automated security and best practice checks
-- 📚 Team learning from AI feedback
-
-Enjoy your new AI code reviewer with quality enforcement! 🤖✨