loki-mode 5.42.2 → 5.46.0

package/docs/git-workflow.md

@@ -0,0 +1,446 @@
+# Git Workflow
+
+Branch protection and Git best practices for Loki Mode (v5.37.0).
+
+## Overview
+
+Loki Mode includes branch protection features that prevent direct commits to main/master branches and enforce a clean PR-based workflow. This ensures code review, quality gates, and audit trails for all changes made by autonomous agents.
+
+## Branch Protection (v5.37.0)
+
+### Enable Branch Protection
+
+```bash
+export LOKI_BRANCH_PROTECTION=true
+loki start ./prd.md
+```
+
+When enabled, Loki Mode automatically:
+
+1. Creates a feature branch: `loki/session-<timestamp>-<pid>`
+2. Performs all agent work on the feature branch
+3. Creates a PR at session end (if GitHub CLI is available)
+4. Requires manual review and merge to main
+
+### Feature Branch Naming
+
+Branches are automatically named using this pattern:
+
+```
+loki/session-<timestamp>-<pid>
+```
+
+Examples:
+- `loki/session-20260215-143022-12345`
+- `loki/session-20260215-150430-67890`
+
+### Workflow
+
+```
+Session Start
+    ↓
+Create feature branch (loki/session-*)
+    ↓
+Agent makes changes on feature branch
+    ↓
+Commit changes to feature branch
+    ↓
+Session Complete
+    ↓
+Create PR: feature branch → main
+    ↓
+Manual Review & Approval
+    ↓
+Merge to main (squash commit)
+    ↓
+Delete feature branch
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LOKI_BRANCH_PROTECTION` | `false` | Enable automatic feature branch workflow |
+| `LOKI_BASE_BRANCH` | `main` | Target branch for PRs (or `master` if detected) |
+| `LOKI_BRANCH_PREFIX` | `loki/session-` | Prefix for auto-created branches |
+| `LOKI_AUTO_PR` | `true` | Automatically create PR at session end |
+| `LOKI_PR_TEMPLATE` | - | Path to PR description template |
+
+### Configuration File
+
+```yaml
+# .loki/config.yaml
+git:
+  branch_protection:
+    enabled: true
+    base_branch: main
+    branch_prefix: loki/session-
+    auto_pr: true
+    squash_merge: true
+    delete_after_merge: true
+```
+
+## Manual Git Workflow
+
+If branch protection is disabled, follow these best practices:
+
+### 1. Create Feature Branch
+
+```bash
+git checkout -b feature/my-feature
+```
+
+### 2. Run Loki Mode
+
+```bash
+loki start ./prd.md
+```
+
+### 3. Review Changes
+
+```bash
+git log --oneline
+git diff main
+```
+
+### 4. Create Pull Request
+
+```bash
+# Using GitHub CLI
+gh pr create --title "Add my feature" --body "Description"
+
+# Or push and create PR manually
+git push origin feature/my-feature
+# Then create PR on GitHub.com
+```
+
+### 5. Review and Merge
+
+- Request code review from team
+- Address feedback
+- Merge when approved
+
+## Pull Request Creation
+
+### Automatic PR Creation
+
+When `LOKI_AUTO_PR=true` and GitHub CLI is installed:
+
+```bash
+# Loki Mode automatically runs at session end
+gh pr create \
+  --title "Loki Mode session $(date +%Y-%m-%d)" \
+  --body "$(cat .loki/session-summary.md)" \
+  --base main \
+  --head loki/session-20260215-143022-12345
+```
+
+### PR Description Template
+
+Create a template for consistent PR descriptions:
+
+```markdown
+# .loki/pr-template.md
+
+## Changes
+
+<!-- Auto-generated summary of changes -->
+
+## Tasks Completed
+
+<!-- List of completed tasks from task queue -->
+
+## Quality Gates
+
+- [ ] All tests passing
+- [ ] Code review completed
+- [ ] No security vulnerabilities
+- [ ] Documentation updated
+
+## Cost
+
+Estimated cost: $X.XX USD
+
+## Session Info
+
+- Start: YYYY-MM-DD HH:MM:SS
+- End: YYYY-MM-DD HH:MM:SS
+- Duration: X hours
+- Iterations: X
+- Provider: claude/codex/gemini
+```
+
+Set template path:
+
+```bash
+export LOKI_PR_TEMPLATE=.loki/pr-template.md
+```
+
+## Agent Action Audit
+
+All Git operations performed by agents are logged to `.loki/logs/agent-audit.jsonl`:
+
+```json
+{
+  "timestamp": "2026-02-15T14:30:00Z",
+  "action": "git_commit",
+  "agent": "development",
+  "branch": "loki/session-20260215-143022-12345",
+  "details": {
+    "message": "Add authentication module",
+    "files_changed": 3,
+    "insertions": 150,
+    "deletions": 20
+  }
+}
+```
+
+View audit log:
+
+```bash
+loki audit log
+loki audit log --action git_commit
+```
+
+## Git Hooks
+
+Loki Mode respects Git hooks:
+
+### Pre-commit Hook
+
+Validate changes before commit:
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+
+# Run linter
+npm run lint
+
+# Run tests
+npm test
+
+# Check for secrets
+git diff --cached | grep -E "(API_KEY|SECRET|PASSWORD)" && exit 1
+
+exit 0
+```
+
+### Pre-push Hook
+
+Prevent direct pushes to main:
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-push
+
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+  echo "ERROR: Direct push to $BRANCH is not allowed"
+  echo "Please create a feature branch and submit a PR"
+  exit 1
+fi
+```
+
+## Best Practices
+
+### For Loki Mode Sessions
+
+1. **Always enable branch protection in production**:
+```bash
+export LOKI_BRANCH_PROTECTION=true
+```
+
+2. **Review changes before merging**:
+```bash
+# Check PR diff
+gh pr diff 123
+
+# View commits
+gh pr view 123 --web
+```
+
+3. **Use squash merge** to keep history clean:
+```bash
+gh pr merge 123 --squash
+```
+
+4. **Delete feature branches after merge**:
+```bash
+gh pr merge 123 --delete-branch
+```
+
+### For Development Teams
+
+1. **Require PR reviews** (configure in GitHub repo settings)
+2. **Enable status checks** (CI/CD must pass)
+3. **Use CODEOWNERS** for automatic reviewers
+4. **Enable branch protection rules** in GitHub
+5. **Require signed commits** for audit trail
+
+### For Audit Compliance
+
+1. Enable audit logging to track all Git operations
+2. Configure branch protection in repo settings
+3. Require approval from CODEOWNERS
+4. Enable commit signing (GPG)
+5. Retain Git history (no force pushes)
+
+## Integration with GitHub Actions
+
+### Automatic PR Creation Workflow
+
+```yaml
+# .github/workflows/loki-pr.yml
+name: Loki PR Creation
+on:
+  push:
+    branches:
+      - 'loki/session-*'
+
+jobs:
+  create-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Create Pull Request
+        run: |
+          gh pr create \
+            --title "Loki Mode session $(date +%Y-%m-%d)" \
+            --body-file .loki/session-summary.md \
+            --base main
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### Automatic Code Review
+
+```yaml
+# .github/workflows/loki-review.yml
+name: Loki Code Review
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: asklokesh/loki-mode@v5
+        with:
+          mode: review
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+## Troubleshooting
+
+### Branch Already Exists
+
+```bash
+# List existing Loki branches
+git branch -a | grep loki/session
+
+# Delete old session branch
+git branch -D loki/session-20260214-120000-11111
+
+# Or delete remote branch
+git push origin --delete loki/session-20260214-120000-11111
+```
+
+### PR Creation Fails
+
+```bash
+# Check GitHub CLI is installed
+gh --version
+
+# Authenticate GitHub CLI
+gh auth login
+
+# Check repository permissions
+gh repo view
+
+# Manually create PR
+gh pr create --title "My PR" --body "Description"
+```
+
+### Merge Conflicts
+
+```bash
+# Update feature branch with latest main
+git checkout loki/session-20260215-143022-12345
+git fetch origin
+git merge origin/main
+
+# Resolve conflicts
+git status
+# Edit conflicted files
+git add .
+git commit -m "Resolve merge conflicts"
+
+# Push updated branch
+git push origin loki/session-20260215-143022-12345
+```
+
+### Detached HEAD State
+
+```bash
+# Check current state
+git status
+
+# Return to feature branch
+git checkout loki/session-20260215-143022-12345
+
+# Or create new branch from current commit
+git checkout -b loki/session-new
+```
+
+## Security
+
+### Prevent Secrets in Commits
+
+Use Git hooks or pre-commit framework:
+
+```bash
+# Install pre-commit
+pip install pre-commit
+
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    hooks:
+      - id: detect-private-key
+      - id: detect-aws-credentials
+  - repo: https://github.com/Yelp/detect-secrets
+    hooks:
+      - id: detect-secrets
+```
+
+### Signed Commits
+
+Require GPG-signed commits:
+
+```bash
+# Generate GPG key
+gpg --gen-key
+
+# Configure Git to sign commits
+git config --global user.signingkey YOUR_KEY_ID
+git config --global commit.gpgsign true
+
+# Verify signature
+git log --show-signature
+```
+
+## See Also
+
+- [Audit Logging](audit-logging.md) - Track Git operations
+- [GitHub Integration](../skills/github-integration.md) - Issue import and PR creation
+- [Enterprise Features](../wiki/Enterprise-Features.md) - Branch protection setup
+- [Contributing](../CONTRIBUTING.md) - Contribution guidelines