forge-workflow 0.0.1

package/docs/research/pr4-cli-automation.md

@@ -0,0 +1,326 @@
+# Research: PR4 - CLI Command Automation
+
+**Date**: 2026-02-14
+**Feature**: Automate Forge workflow commands with executable CLI dispatcher
+
+---
+
+## Objective
+
+Transform Forge from **documentation-driven workflow** to **CLI-automated workflow**.
+
+**Deliverables**:
+1. Executable command dispatcher (`bin/forge-cmd.js`)
+2. Intelligent stage detection (auto-detect workflow stage 1-9)
+3. Automated command handlers (`/research`, `/plan`, `/ship`, `/review`)
+4. PR body auto-generation (from research + plan + tests)
+5. Review aggregation (Greptile + SonarCloud + GitHub Actions)
+
+---
+
+## Codebase Analysis
+
+### Current Architecture
+
+**CLI Entry Points**:
+- `bin/forge.js` (3,800+ lines) - Setup with agent configuration
+- `bin/forge-validate.js` (304 lines) - Validation with switch dispatch
+
+**Commands**: `.claude/commands/` - 11 markdown files defining workflow stages
+
+**Critical Gap**: Commands are documentation only, not executable code
+
+### Existing Patterns to Follow
+
+**State Management** (lib/setup.js):
+- saveSetupState() - Persist progress
+- loadSetupState() - Resume from last state
+- isSetupComplete() - Check completion
+
+**Validation Pattern** (bin/forge-validate.js):
+- Modular dispatch with switch statement
+- Separate handler functions per command
+- Export for testing
+
+**Test Infrastructure**:
+- 576 tests across 36 files
+- E2E framework with fixtures
+- Snapshot testing
+- 80% coverage thresholds
+
+---
+
+## Security Analysis (OWASP Top 10)
+
+### A03: Injection (CRITICAL for CLI)
+
+**Command Injection Risk**:
+- User input in `/research <name>`, `/plan <slug>`
+- **Mitigation**: Never use exec() with user input
+
+**Safe Pattern**:
+```javascript
+// UNSAFE
+exec(`gh pr create --title "${userInput}"`);
+
+// SAFE
+execFile('gh', ['pr', 'create', '--title', userInput]);
+```
+
+**Input Validation**:
+- Feature slugs: `/^[a-z0-9-]+$/` only
+- No spaces, dots, slashes
+- Max length: 50 characters
+
+**Path Traversal Prevention**:
+```javascript
+const slug = path.basename(userInput); // Strip paths
+if (!/^[a-z0-9-]+$/.test(slug)) {
+  throw new Error('Invalid feature slug');
+}
+```
+
+### A01: Broken Access Control
+
+**File Permission Checks**:
+```javascript
+fs.accessSync(dir, fs.constants.W_OK); // Check before write
+```
+
+**Git Repository Validation**:
+```javascript
+// Verify correct repo before operations
+const config = fs.readFileSync('.git/config', 'utf-8');
+if (!config.includes('expected-repo')) {
+  throw new Error('Wrong repository');
+}
+```
+
+### A04: Insecure Design
+
+**Stage Prerequisites**:
+- Don't run `/ship` before `/validate` passes
+- Validate workflow order
+- Provide clear error messages
+
+**Idempotency**:
+- Check existing state before creating resources
+- Don't duplicate PRs, branches, Beads issues
+- Safe to re-run commands
+
+### A05: Security Misconfiguration
+
+**Secret Management**:
+- Read from `.env.local` (already implemented)
+- Never log full API keys (show first 6 chars only)
+- Redact secrets in error messages
+
+### Security Checklist
+
+- [ ] All user input validated with `/^[a-z0-9-]+$/`
+- [ ] No exec() with user input
+- [ ] Path traversal prevented
+- [ ] File permissions checked
+- [ ] Git repo validated
+- [ ] Stage prerequisites validated
+- [ ] Idempotency implemented
+- [ ] API keys never logged
+- [ ] API responses validated
+- [ ] Atomic file writes
+- [ ] Dangerous operations require confirmation
+
+---
+
+## Key Decisions
+
+### Decision 1: Plain Node.js (No CLI Framework)
+
+**What**: Use plain Node.js without Commander.js/yargs/oclif
+
+**Why**:
+- Forge has established patterns (bin/forge-validate.js)
+- Custom logic needed
+- No framework overhead
+- Testing infrastructure in place
+
+**Alternatives Rejected**:
+- Commander.js (unnecessary for 9 commands)
+- Yargs (too complex)
+- oclif (heavyweight)
+
+### Decision 2: Command Dispatcher Architecture
+
+**Pattern**:
+```
+bin/forge-cmd.js (CLI entrypoint)
+  ↓
+lib/commands/
+  ├── status.js       → Stage detection
+  ├── research.js     → Parallel-AI automation
+  ├── plan.js         → Branch + plan + OpenSpec
+  ├── ship.js         → PR body generation
+  └── review.js       → Review aggregation
+```
+
+**Why**: Separation of concerns, testability
+
+### Decision 3: Stage Detection Algorithm
+
+**Multi-factor with confidence scoring**:
+
+Factors:
+1. Branch state (exists, commits, matches PR)
+2. File existence (research doc, plan, tests)
+3. PR state (open, reviews, approval)
+4. Check results (CI/CD status)
+5. Beads issue state
+
+Confidence:
+- High (90-100%): All indicators consistent
+- Medium (70-89%): Most agree
+- Low (<70%): Conflicting, suggest manual override
+
+### Decision 4: Review Aggregation Format
+
+**Output**:
+```
+✓ Review Aggregation: 24 issues
+
+Critical (3):
+  1. [Greptile] SQL injection (src/api/users.js:42)
+  2. [SonarCloud] Security hotspot (src/auth/login.js:78)
+  3. [GitHub Actions] Build failed
+
+High (8):
+  4. [Greptile] Missing error handling (...)
+  ...
+```
+
+**Why**: Consolidated, prioritized feedback
+
+---
+
+## TDD Test Scenarios
+
+### Test 1: Stage Detection
+
+```javascript
+test('detect stage 1 when no branch, no research', () => {
+  const stage = detectStage(freshProject);
+  assert.strictEqual(stage.stage, 1);
+  assert.strictEqual(stage.confidence, 'high');
+});
+```
+
+### Test 2: Research Automation
+
+```javascript
+test('create research doc from parallel-ai', async () => {
+  mockParallelAI({ results: [{ title: 'Best practices' }] });
+
+  await researchCommand(fixture, 'stripe-billing');
+
+  const doc = readFile(fixture, 'docs/research/stripe-billing.md');
+  assert.ok(doc.includes('# Research: Stripe Billing'));
+});
+```
+
+### Test 3: PR Body Generation
+
+```javascript
+test('generate PR body from all sources', async () => {
+  createFile(fixture, 'docs/research/feature.md', RESEARCH);
+  createFile(fixture, '.claude/plans/feature.md', PLAN);
+
+  const prBody = await generatePRBody(fixture, 'feature');
+
+  assert.ok(prBody.includes('## Summary'));
+  assert.ok(prBody.includes('## Key Decisions'));
+});
+```
+
+### Test 4: Review Aggregation
+
+```javascript
+test('aggregate all review sources', async () => {
+  mockGitHubAPI({ checks: [{ name: 'Tests', status: 'failed' }] });
+  mockGreptileAPI({ comments: [{ severity: 'critical' }] });
+
+  const review = await aggregateReview(123);
+
+  assert.strictEqual(review.critical.length, 1);
+});
+```
+
+### Test 5: E2E Workflow
+
+```javascript
+test('complete research workflow end-to-end', async () => {
+  execSync('node bin/forge-cmd.js status', { cwd: fixture });
+  execSync('node bin/forge-cmd.js research test-feature', { cwd: fixture });
+  execSync('node bin/forge-cmd.js plan test-feature', { cwd: fixture });
+
+  const branch = execSync('git branch --show-current', { cwd: fixture });
+  assert.ok(branch.includes('feat/test-feature'));
+});
+```
+
+---
+
+## Scope Assessment
+
+**Complexity**: High
+- Multiple handlers with complex logic
+- API integrations (GitHub, Greptile, SonarCloud)
+- Intelligent stage detection
+- PR body generation from multiple sources
+
+**Type**: Strategic (architecture change, requires OpenSpec)
+
+**Timeline**: 3-4 days
+- Day 1: Dispatcher + /status enhancement
+- Day 2: /research + /plan automation
+- Day 3: /ship + /review automation
+- Day 4: Testing + documentation
+
+**Dependencies**:
+- ✅ PR3 (Testing Infrastructure) - COMPLETE
+- Beads CLI (`bd`)
+- GitHub CLI (`gh`)
+- Parallel AI API key
+
+**Risks**:
+1. API rate limits → Caching, retry logic
+2. Complex stage detection → Confidence scoring
+3. Integration testing → Fixtures, mocking
+
+---
+
+## Sources
+
+**Codebase**:
+- bin/forge.js, bin/forge-validate.js
+- .claude/commands/*.md
+- lib/setup.js (state management)
+- test/e2e/ (E2E patterns)
+
+**Web Research** (Parallel AI):
+- Command Pattern in Node (Medium)
+- Node.js Best Practices
+- Multi-Agent Systems
+- Workflow orchestration patterns
+
+**Security**:
+- OWASP Top 10 2021
+- CWE-78 (Command Injection)
+- CWE-22 (Path Traversal)
+
+---
+
+## Next: /plan pr4-cli-automation
+
+Create OpenSpec proposal with:
+1. Command dispatcher architecture
+2. Stage detection algorithm
+3. Security mitigations
+4. Test strategy

package/docs/research/premerge-verify-restructure.md

@@ -0,0 +1,205 @@
+# Research: /premerge + /verify Workflow Restructure
+
+**Date**: 2026-02-24
+**Objective**: Determine if restructuring `/merge` → `/premerge` (pre-merge doc prep) and making `/verify` read-only is the right approach, and identify potential problems.
+
+---
+
+## Codebase Analysis
+
+### Current State
+
+| Component | Location | Status |
+| --- | --- | --- |
+| `/merge` command | `.claude/commands/merge.md` | Exists — currently does docs + handoff |
+| `/verify` command | `.claude/commands/verify.md` | Exists — finds gaps, commits fixes, can create PRs |
+| Workflow table (stage 8) | `CLAUDE.md`, `AGENTS.md`, `docs/WORKFLOW.md`, all 11 command files | All say `/merge` |
+
+### The Loop Problem
+
+```
+/merge → doc commits → PR
+User merges
+/verify → finds gaps → commits to master → PROTECTED → needs new PR
+User merges again
+/verify again?
+```
+
+Every post-merge doc fix requires its own PR because `master` is branch-protected.
+
+---
+
+## Web Research Findings
+
+### Finding 1: Post-merge doc commits on protected branches are fundamentally broken
+
+**Source**: Multiple CI/CD resources (Terramate, Medium, GitHub Docs)
+
+Post-merge commits to protected branches fail because:
+- They bypass the PR validation flow
+- Squash merges create "phantom conflicts" when the same branch is re-merged
+- Stale approval dismissal means post-merge commits lose approval status
+- Each failure requires another follow-up PR → recursive loop
+
+**Verdict**: Our problem is a known anti-pattern. Pre-merge documentation is the correct fix.
+
+---
+
+### Finding 2: Pre-merge documentation is the correct pattern
+
+**Source**: LinearB, GitHub Actions best practices, Graphite
+
+Successful teams enforce documentation as part of the PR itself — not as a follow-up. The PR is only ready to merge when it contains code + tests + docs.
+
+**Verdict**: Moving doc updates into the feature branch (before handoff) is confirmed correct.
+
+---
+
+### Finding 3: Keep pre-merge checks fast and focused
+
+**Source**: ZenCoder AI, LinearB
+
+Overly complex pre-merge checklists slow down merging and get skipped. Each check should be targeted and relevant to the specific PR.
+
+**Verdict**: `/premerge` should check only docs that are actually relevant to the feature — not a blanket update of all files every time.
+
+---
+
+## Problems We Could Face
+
+### Problem 1: Simultaneous PRs conflict on shared doc files
+
+If two PRs are open and both update `PROGRESS.md` or `CLAUDE.md`, one will have a merge conflict.
+
+**Mitigation**: `/premerge` should warn if the branch is behind `master` and tell user to rebase first. Since user merges sequentially, this is rare but possible.
+
+---
+
+### Problem 2: CLAUDE.md has managed sections that must not be touched
+
+`CLAUDE.md` has `<!-- OPENSPEC:START/END -->` and `<!-- USER:START/END -->` blocks managed by external tools. Breaking the structure causes `openspec update` to fail.
+
+**Mitigation**: `/premerge` must only update the **USER section** (between `<!-- USER:START -->` and `<!-- USER:END -->`). Never modify managed blocks.
+
+---
+
+### Problem 3: Doc commits on feature branch re-trigger full CI
+
+When `/premerge` pushes doc update commits, Greptile and other CI tools re-run. This could add new Greptile review comments on the documentation changes.
+
+**Mitigation**: This is acceptable — doc updates should be reviewed. `/premerge` output should tell the user to re-check CI after the doc push, and run `/review` again if needed.
+
+---
+
+### Problem 4: Stage 8 label `/merge` appears in 4+ locations
+
+The workflow table with stage 8 = `/merge` exists in:
+1. `CLAUDE.md`
+2. `AGENTS.md`
+3. `docs/WORKFLOW.md` (407 lines)
+4. The "Integration with Workflow" section inside **each of the 11 command files**
+
+Missing any of these creates inconsistency.
+
+**Mitigation**: Update all locations as part of the implementation PR. The 11 command files are the easiest to miss.
+
+---
+
+### Problem 5: `/verify` becomes nearly trivial
+
+If all doc updates happen pre-merge, `/verify` has almost nothing to do post-merge. Risk: it gets skipped entirely.
+
+**Mitigation**: Give `/verify` a clear, focused purpose:
+- `git checkout master && git pull` (update local)
+- Confirm the feature entry is in `PROGRESS.md` on main (quick sanity check)
+- Output "clean — ready for next feature, run /status"
+- If something IS missing: create a Beads issue, never commit inline
+
+This makes it lightweight and always worth running.
+
+---
+
+### Problem 6: PR #47 already open with the old merge.md update
+
+PR #47 currently contains the old `merge.md` update (handoff-only version). Now we're replacing it with `premerge.md` + updated `verify.md` + all doc references.
+
+**Mitigation**: Amend the same branch (`fix/merge-command-no-auto-merge`) — add `premerge.md`, delete `merge.md`, update everything. PR #47 will automatically update.
+
+---
+
+## Clarified Command Design (Final)
+
+### `/premerge <pr-number>` — Everything before the user clicks merge
+
+All documentation and changes go here. The PR must be 100% complete before handoff.
+
+Checklist:
+- All CI checks passing
+- Branch up to date with master (warn if behind)
+- `PROGRESS.md` updated
+- `README.md` updated (if user-facing)
+- `API_REFERENCE.md` updated (if API changes)
+- Architecture docs updated (if structural)
+- `CLAUDE.md` USER section updated (if conventions changed)
+- `AGENTS.md` updated (if agent config/skills changed)
+- `docs/WORKFLOW.md` updated (if workflow changed)
+- Commit all doc updates to feature branch → push
+- Archive OpenSpec (if strategic)
+- Sync Beads
+- **STOP** → present PR URL → wait for user to merge
+
+### `/verify` — Post-merge health check (not a doc check)
+
+Runs AFTER user confirms they've merged. Focuses on system health, not documentation.
+
+Checklist:
+- `git checkout master && git pull` (confirm merge landed)
+- Did CI pass on main after merge? (`gh run list --branch master --limit 3`)
+- Are deployments up? (Vercel preview → production, or other deploy targets)
+- Any post-merge failures or broken checks on main?
+- Is the PR marked as merged (not just closed)?
+- If any issues: report them clearly — these may need hotfix PRs
+
+**Never commits.** If documentation gaps are found at this stage, create a Beads issue rather than committing inline.
+
+---
+
+## Key Decisions
+
+### Decision 1: Delete `/merge`, create `/premerge` — don't alias
+
+**Why**: An alias creates confusion. Clean break is better.
+
+**Evidence**: User confirmed "delete it."
+
+### Decision 2: `/verify` = post-merge health check, not doc verification
+
+**Why**: Documentation completeness is `/premerge`'s job. `/verify` should answer: "did everything land and run correctly after the merge?" — deployments, CI on main, merge status.
+
+**Evidence**: User explicitly clarified this: "check if the pull request has been merged properly, if deployments are working properly, if we are facing any issues."
+
+### Decision 3: `/premerge` owns ALL documentation updates
+
+**Why**: Eliminates the recursive PR loop entirely. The PR contains code + tests + docs as a single complete unit. User merges once.
+
+**Evidence**: Web research confirms pre-merge documentation is the correct pattern. Post-merge commits on protected branches are a known anti-pattern.
+
+---
+
+## Scope Assessment
+
+**Tactical** (no OpenSpec needed) — this is a workflow command update, not an architecture change.
+
+**Complexity**: Medium — 4+ files to update, careful with managed sections in CLAUDE.md.
+
+**Risk**: Low — command files are documentation, no code logic affected.
+
+---
+
+## Sources
+
+- [GitHub Docs: Managing branch protection rules](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule)
+- [Mastering Terraform Workflows: apply-before-merge vs apply-after-merge](https://terramate.io/rethinking-iac/mastering-terraform-workflows-apply-before-merge-vs-apply-after-merge/)
+- [The case for apply before merge](https://medium.com/@DiggerHQ/the-case-for-apply-before-merge-bc08a7a9bfea)
+- [LinearB: Pre-merge Workflow Automation](https://linearb.io/resources/automate-pre-merge-workflow-automation-for-dev-efficiency)
+- [Graphite: Mandatory pull request checks](https://graphite.com/guides/mandatory-pull-request-checks-and-requirements-in-github)