diff --git a/CREATE_INDIVIDUAL_PRS.md b/CREATE_INDIVIDUAL_PRS.md new file mode 100644 index 00000000..c284e16e --- /dev/null +++ b/CREATE_INDIVIDUAL_PRS.md @@ -0,0 +1,146 @@ +# How to Create Individual Draft PRs from Plan Branches + +## Current Situation + +All implementation plans have been created and stored in two places: + +1. **Organized in subdirectories** (on branch `copilot/analyze-issues-create-prs`): + - `plan-issue-100/PLAN.md` - npm audit vulnerabilities + - `plan-issue-98/PLAN.md` - glob patterns in file transfer + - `plan-issue-96/PLAN.md` - Windows installer fix + - `plan-issue-92/PLAN.md` - PM deploy.md sourcing + - `plan-issue-91/PLAN.md` - git worktree bug + - `plan-issue-90/PLAN.md` - claude --auto permissions + - `plan-issue-77/PLAN.md` - Slack notifications + - `plan-issue-76/PLAN.md` - GitHub App research + +2. **Individual branches** (local only, not pushed): + - `plan/issue-100-npm-audit` + - `plan/issue-98-glob-patterns` + - `plan/issue-96-windows-installer` + - `plan/issue-92-pm-deploy-md` + - `plan/issue-91-git-worktree` + - `plan/issue-90-claude-auto` + - `plan/issue-77-slack-notifications` + - `plan/issue-76-github-app-research` + +## Limitation + +The bot cannot push branches directly to the repository due to permission constraints. The `report_progress` tool only pushes to a single PR branch (`copilot/analyze-issues-create-prs`). + +## Manual Steps to Create Individual PRs + +### Option 1: Using Local Branches (Recommended) + +If you have push access to the repository, you can push the local branches and create PRs: + +```bash +cd /path/to/apra-fleet + +# Push all plan branches +for branch in plan/issue-100-npm-audit plan/issue-98-glob-patterns plan/issue-96-windows-installer plan/issue-92-pm-deploy-md plan/issue-91-git-worktree plan/issue-90-claude-auto plan/issue-77-slack-notifications plan/issue-76-github-app-research; do + git push origin $branch +done + +# Create draft PRs using gh CLI +gh pr create --head plan/issue-100-npm-audit --draft --title "Plan: Track and resolve npm audit vulnerabilities" --body "Implementation plan for issue #100. See PLAN.md for details." +gh pr create --head plan/issue-98-glob-patterns --draft --title "Plan: Support glob patterns in file transfer" --body "Implementation plan for issue #98. See PLAN.md for details." +gh pr create --head plan/issue-96-windows-installer --draft --title "Plan: Fix Windows installer file lock" --body "Implementation plan for issue #96. See PLAN.md for details." +gh pr create --head plan/issue-92-pm-deploy-md --draft --title "Plan: Source deploy.md from git root" --body "Implementation plan for issue #92. See PLAN.md for details." +gh pr create --head plan/issue-91-git-worktree --draft --title "Plan: Fix git worktree corruption bug" --body "Implementation plan for issue #91. See PLAN.md for details." +gh pr create --head plan/issue-90-claude-auto --draft --title "Plan: Use claude --auto permissions" --body "Implementation plan for issue #90. See PLAN.md for details." +gh pr create --head plan/issue-77-slack-notifications --draft --title "Plan: Slack notifications for fleet" --body "Implementation plan for issue #77. See PLAN.md for details." +gh pr create --head plan/issue-76-github-app-research --draft --title "Research: GitHub App token limitations" --body "Research plan for issue #76. See PLAN.md for details." +``` + +### Option 2: Recreate from Subdirectories + +If the local branches are not available, you can recreate them from the subdirectories: + +```bash +cd /path/to/apra-fleet + +# Checkout the branch with all plans +git fetch origin +git checkout copilot/analyze-issues-create-prs + +# For each issue, create a branch and copy the plan +for issue in 100 98 96 92 91 90 77 76; do + git checkout -b plan/issue-${issue} origin/main + cp plan-issue-${issue}/PLAN.md ./PLAN.md + git add PLAN.md + git commit -m "Plan: Implementation plan for issue #${issue}" + git push origin plan/issue-${issue} +done + +# Then create PRs as shown in Option 1 +``` + +### Option 3: Using Git Patches + +Git patches have been created for each plan and can be applied: + +```bash +# Patches are available in /tmp/plan-patches/ on the bot's machine +# To use them, you would need to: +# 1. Get the patch files from the bot +# 2. Apply each patch to create the branch +# 3. Push and create PRs + +# Example for one issue: +git checkout -b plan/issue-100 origin/main +git am < issue-100.patch +git push origin plan/issue-100 +gh pr create --head plan/issue-100 --draft --title "Plan: npm audit fix" --body "Plan for #100" +``` + +## Automated Script + +A helper script is available that automates the process (requires push permissions): + +```bash +#!/bin/bash +set -e + +# Array of issues +declare -A issues +issues[100]="Track and resolve npm audit vulnerabilities" +issues[98]="Support glob patterns and directories in file transfer" +issues[96]="Fix Windows installer file lock issue" +issues[92]="Source deploy.md from project git root" +issues[91]="Fix git worktree path corruption bug" +issues[90]="Use claude --auto permissions for Team/Enterprise" +issues[77]="Slack notifications for fleet state changes" +issues[76]="Research GitHub App installation token scope limitations" + +# For each issue +for issue in "${!issues[@]}"; do + branch="plan/issue-${issue}" + title="${issues[$issue]}" + + echo "Processing issue #${issue}..." + + # Push branch + if git push origin ${branch} 2>/dev/null; then + echo " ✓ Pushed ${branch}" + + # Create PR + gh pr create \ + --head ${branch} \ + --title "Plan: ${title}" \ + --body "Implementation plan for issue #${issue}. See PLAN.md for details." \ + --draft && echo " ✓ Created PR" + else + echo " ✗ Failed to push ${branch}" + fi +done +``` + +## Summary + +The bot has created all the implementation plans but cannot push them individually due to permission constraints. Manual intervention is required to: + +1. Push the plan branches to the repository +2. Create individual draft PRs for each issue + +All necessary content is prepared and ready; it just needs to be pushed with appropriate permissions. diff --git a/ISSUE_TRIAGE_SUMMARY.md b/ISSUE_TRIAGE_SUMMARY.md new file mode 100644 index 00000000..6868fb95 --- /dev/null +++ b/ISSUE_TRIAGE_SUMMARY.md @@ -0,0 +1,576 @@ +# Issue Triage Summary +**Date:** 2026-04-08 +**Bot:** GitHub Copilot Agent +**Task:** Analyze open issues, create PRs for simple fixes, create plans for complex issues + +## Summary + +**Total Issues Analyzed:** 10 +**Issues Skipped (has PR):** 1 +**Simple Fixes (PR created):** 1 +**Complex Issues (plan needed):** 8 + +--- + +## Issue-by-Issue Analysis + +### ✅ Issue #103: Fleet uniqueness check should use host+port+folder +**Status:** SKIPPED - Already has PR #104 (draft) +**Complexity:** Simple (would be 10-15 lines, 2 files) +**Action:** None - PR already exists + +--- + +### ✅ Issue #99: cleanup.md blindly removes CLAUDE.md and AGENTS.md +**Status:** FIXED - PR #105 created (draft) +**Complexity:** Simple (1 file, 1 line changed) +**Files Changed:** +- `skills/pm/cleanup.md` + +**Fix Summary:** +Modified cleanup command to check if files are tracked by git before removing them: +```bash +for file in CLAUDE.md GEMINI.md AGENTS.md COPILOT-INSTRUCTIONS.md; do + git ls-files --error-unmatch "$file" 2>/dev/null || rm -f "$file" +done +``` + +This prevents accidental deletion of sprint deliverables that share names with ephemeral agent context files. + +**Recommendation:** ✓ Ready for review - add `bot_reviewed` label + +--- + +### 📋 Issue #100: Track and resolve transitive dependency vulnerabilities +**Status:** NEEDS PLAN +**Complexity:** Complex (dependency updates, testing, potential breaking changes) + +**Analysis:** +- 6 high severity vulnerabilities in transitive dependencies +- Root cause: outdated `@modelcontextprotocol/sdk` +- Fix involves `npm audit fix` which adds 49 packages, changes 7 +- Risk of breaking API changes from SDK update + +**Plan:** + +#### Phase 1: Assessment +- [ ] Run `npm audit` to get current baseline +- [ ] Run `npm audit fix --dry-run` to see proposed changes +- [ ] Review changelog for `@modelcontextprotocol/sdk` between current and proposed versions +- [ ] Identify any breaking API changes + +#### Phase 2: Update Dependencies +- [ ] Create feature branch `fix/npm-audit-vulnerabilities` +- [ ] Run `npm audit fix` +- [ ] Review `package-lock.json` changes +- [ ] Update any code affected by SDK API changes + +#### Phase 3: Testing +- [ ] Run full test suite: `npm test` +- [ ] Manual testing of MCP server startup +- [ ] Test all MCP tools (register_member, execute_prompt, etc.) +- [ ] Verify no regressions in fleet operations + +#### Phase 4: Verification +- [ ] Confirm `npm audit` reports 0 high/critical vulnerabilities +- [ ] All existing tests pass +- [ ] No breaking changes to MCP tool interfaces +- [ ] Update documentation if SDK changes affect usage + +**Estimated Effort:** 2-4 hours +**Files Affected:** `package.json`, `package-lock.json`, potentially TypeScript files using MCP SDK + +**Recommendation:** Create this plan as a comment on issue #100, add `bot_reviewed` label + +--- + +### 📋 Issue #98: Support glob patterns and directories in send_files/receive_files +**Status:** NEEDS PLAN +**Complexity:** Medium-Complex (4 files, SFTP integration, testing) + +**Analysis:** +- Currently only accepts individual file paths +- Need to support glob patterns (`tests/*.ts`) and directories (`src/`) +- Affects file transfer core functionality +- Tagged as "good first issue" but requires Node.js fs and SSH/SFTP knowledge + +**Plan:** + +#### Phase 1: Research & Design +- [ ] Review current `send_files` and `receive_files` implementation +- [ ] Research Node.js glob libraries (e.g., `glob`, `fast-glob`) +- [ ] Review SFTP library capabilities for recursive transfers +- [ ] Design API: should patterns be expanded client-side or server-side? + +#### Phase 2: Implementation +- [ ] Add glob pattern expansion in `src/services/file-transfer.ts` + - Handle directory recursion + - Handle glob patterns (e.g., `**/*.ts`) + - Preserve directory structure +- [ ] Update `src/services/sftp.ts` + - Modify `uploadViaSFTP` to handle multiple files/directories + - Modify `downloadViaSFTP` to handle multiple files/directories + - Ensure recursive transfer works correctly +- [ ] Update tool schemas in `src/tools/send-files.ts` and `src/tools/receive-files.ts` + - Update parameter descriptions + - Add examples showing glob patterns and directories +- [ ] Add dependency if needed (e.g., `fast-glob`) + - Check for vulnerabilities before adding + +#### Phase 3: Testing +- [ ] Unit tests for glob expansion logic +- [ ] Integration tests for directory transfer +- [ ] Integration tests for glob pattern transfer +- [ ] Test edge cases: + - Empty directories + - Nested directories + - Non-existent patterns + - Mixed paths (some files, some globs) +- [ ] Manual testing with actual SFTP transfers + +#### Phase 4: Documentation +- [ ] Update tool descriptions with examples +- [ ] Update README or documentation with glob pattern usage +- [ ] Add migration notes if behavior changes + +**Estimated Effort:** 4-8 hours +**Files Affected:** +- `src/services/sftp.ts` +- `src/services/file-transfer.ts` +- `src/tools/send-files.ts` +- `src/tools/receive-files.ts` +- Tests files +- Possibly `package.json` for new dependency + +**Recommendation:** Create this plan as a comment on issue #98, add `bot_reviewed` label + +--- + +### 📋 Issue #96: Installer fails on Windows when MCP server is running +**Status:** NEEDS PLAN +**Complexity:** Medium-Complex (platform-specific code, process management) + +**Analysis:** +- Windows locks executables while running +- Need to detect and stop MCP server process before replacing binary +- Platform-specific solution required +- Affects installer scripts + +**Plan:** + +#### Phase 1: Detection +- [ ] Research process detection methods on Windows + - Process name matching (`apra-fleet.exe`) + - PID file approach + - Port-based detection (if MCP server listens on a port) +- [ ] Implement detection in installer scripts + - `install.cmd` for Windows batch + - `install.ps1` for PowerShell + +#### Phase 2: Graceful Shutdown +- [ ] Option 1: HTTP shutdown endpoint + - Add `/shutdown` endpoint to MCP server + - Installer calls endpoint before replacing binary + - Wait for process to exit (with timeout) +- [ ] Option 2: Process termination + - Use `taskkill /IM apra-fleet.exe` on Windows + - Implement with fallback to `/F` flag if graceful fails +- [ ] Implement shutdown logic in installer + +#### Phase 3: Binary Replacement +- [ ] Verify process has stopped before copying +- [ ] Copy new binary with retry logic (handle lingering locks) +- [ ] Set appropriate permissions + +#### Phase 4: Restart/Notification +- [ ] Option 1: Auto-restart MCP server + - May not work if Claude Code needs to reload config +- [ ] Option 2: Notify user to restart Claude Code + - Print clear instructions + - Detect Claude Code process and suggest specific restart + +#### Phase 5: Testing +- [ ] Test on Windows with MCP server running +- [ ] Test graceful shutdown +- [ ] Test forced shutdown +- [ ] Test when server is not running +- [ ] Test restart/notification flow + +**Estimated Effort:** 4-6 hours +**Files Affected:** +- `install.cmd` (Windows batch installer) +- `install.ps1` (PowerShell installer) +- Possibly `src/index.ts` if adding shutdown endpoint +- Documentation/README with installation notes + +**Recommendation:** Create this plan as a comment on issue #96, add `bot_reviewed` label + +--- + +### 📋 Issue #92: PM skill should source deploy.md from project git root +**Status:** NEEDS PLAN +**Complexity:** Complex (workflow changes, PM skill modification) + +**Analysis:** +- Currently deploy.md lives in PM project folder, outside repo +- Need to prioritize repo version, fall back to PM folder +- Create and commit deploy.md on first successful deploy +- Affects PM skill workflow + +**Plan:** + +#### Phase 1: Update PM Skill Logic +- [ ] Modify `skills/pm/single-pair-sprint.md` deploy section + - Add step to check for `deploy.md` in project git root first + - Fall back to `/deploy.md` if not found + - Document the precedence order +- [ ] Add logic for first-time deploy: + - If no `deploy.md` exists anywhere, work with user to create it + - After successful deploy, commit to project git root + - Copy to PM folder for caching + +#### Phase 2: Sync Logic +- [ ] Implement bidirectional sync strategy: + - If repo version newer, use it and update PM folder cache + - If PM folder version has manual changes, prompt to push to repo + - Add timestamp/hash comparison logic +- [ ] Handle conflicts: + - If both versions exist and differ, prompt user to choose + - Show diff if possible + +#### Phase 3: Update Workflow +- [ ] Update PM instructions for deviation handling: + - When deploy process deviates from runbook, update `deploy.md` + - Commit and push updated runbook to repo + - Update PM folder cache +- [ ] Add validation: + - Verify deploy.md is in git root after first successful deploy + - Warn if deploy.md is stale + +#### Phase 4: Testing +- [ ] Test first-time deploy (no deploy.md anywhere) +- [ ] Test with deploy.md in git root only +- [ ] Test with deploy.md in PM folder only +- [ ] Test with both versions (same content) +- [ ] Test with both versions (different content) +- [ ] Test update-and-push workflow + +**Estimated Effort:** 3-5 hours +**Files Affected:** +- `skills/pm/single-pair-sprint.md` +- Possibly PM skill helper scripts +- Documentation + +**Recommendation:** Create this plan as a comment on issue #92, add `bot_reviewed` label + +--- + +### 📋 Issue #91: Git worktree .git file path corrupted by bash shell context +**Status:** NEEDS PLAN +**Complexity:** Complex (server-side changes, agent context, detection logic) + +**Analysis:** +- Git worktrees use `.git` file (not directory) with path to parent repo +- Agents sometimes "fix" the path, breaking it for Windows git.exe +- Need worktree detection and protection mechanisms +- Affects execute_command, execute_prompt, and agent templates + +**Plan:** + +#### Phase 1: Server-Side Worktree Detection +- [ ] Add worktree detection in member registration: + - Check if `work_folder/.git` is a file (not directory) + - Read gitdir path and validate format + - Store worktree flag in member config +- [ ] Add worktree detection in execute_command: + - Before command execution, check for `.git` file + - Set environment flag if worktree detected + +#### Phase 2: Git Command Handling +- [ ] On Windows members with worktrees: + - Always use `git.exe` for push/fetch/pull (not bash git) + - Set GIT_EXEC_PATH or use full path to Windows git binary + - Avoid bash git which may have different path resolution +- [ ] Add git command wrapper: + - Detect if command modifies `.git` file + - Block such modifications + - Return error with explanation + +#### Phase 3: Agent Context Updates +- [ ] Update `tpl-doer.md` or agent templates: + - Add rule: Never modify `.git` files + - If git fails in a worktree, report blocked (don't try to fix) + - Provide clear error message for PM intervention +- [ ] Add worktree troubleshooting guidance: + - Document `git worktree repair` command + - Add to error messages when worktree issues detected + +#### Phase 4: Registration Safeguards +- [ ] Option 1: Warn on worktree registration + - Detect worktree during registration + - Prompt user to confirm or use regular clone instead +- [ ] Option 2: Auto-repair on registration + - Run `git worktree repair` during registration + - Validate path format is correct for platform +- [ ] Add worktree documentation: + - Known limitations + - Recommended workarounds + - How to use worktrees safely with fleet + +#### Phase 5: Testing +- [ ] Test worktree detection logic +- [ ] Test git operations in worktree (Windows) +- [ ] Test .git file protection (block modifications) +- [ ] Test error handling and user messaging +- [ ] Test regular clone (ensure no regression) +- [ ] Test auto-repair if implemented + +**Estimated Effort:** 6-10 hours (complex, multi-component) +**Files Affected:** +- `src/services/execute-command.ts` or similar +- `src/services/execute-prompt.ts` or similar +- `src/tools/register-member.ts` +- Agent template files (tpl-doer.md, etc.) +- Member configuration schema +- Documentation + +**Recommendation:** Create this plan as a comment on issue #91, add `bot_reviewed` label + +--- + +### 📋 Issue #90: Use claude --auto permissions mode for Team/Enterprise +**Status:** NEEDS PLAN +**Complexity:** Medium-Complex (plan detection, conditional logic) + +**Analysis:** +- Claude Code has `--auto` flag for automatic permissions (Team/Enterprise only) +- Need to detect user's plan tier +- Fall back to compose_permissions for Personal plan or detection failure +- Should be silent/graceful fallback + +**Plan:** + +#### Phase 1: Plan Detection Research +- [ ] Research detection methods: + - `claude --version` output analysis + - Claude config file inspection (~/.claude/config or similar) + - API endpoint for account info (if available) + - Environment variable or flag +- [ ] Determine most reliable method +- [ ] Implement detection with error handling + +#### Phase 2: Conditional Logic Implementation +- [ ] Modify dispatch logic (execute_prompt or similar): + - Detect plan tier before dispatch + - If Team/Enterprise: use `--auto` flag + - If Personal or unknown: fall back to compose_permissions +- [ ] Ensure fallback is silent: + - No errors or warnings if detection fails + - Seamless UX for users +- [ ] Cache detection result: + - Store in member config to avoid repeated checks + - Add refresh mechanism if plan changes + +#### Phase 3: Testing +- [ ] Test with Team/Enterprise account (if available) + - Verify `--auto` flag is used + - Verify permissions work correctly +- [ ] Test with Personal account + - Verify fallback to compose_permissions + - Verify no errors or warnings +- [ ] Test with detection failure + - Simulate API error, missing config, etc. + - Verify graceful fallback +- [ ] Test plan upgrade scenario + - User upgrades from Personal to Team + - Verify detection refresh works + +#### Phase 4: Documentation +- [ ] Update `skills/fleet/permissions.md`: + - Document `--auto` mode + - Explain plan detection + - Explain fallback behavior +- [ ] Update member registration docs: + - Mention plan tier detection + - How to force compose_permissions if needed + +**Estimated Effort:** 3-5 hours +**Files Affected:** +- Dispatch/execution logic (execute_prompt or similar) +- Member configuration schema (for caching plan tier) +- `skills/fleet/permissions.md` +- Tests + +**Recommendation:** Create this plan as a comment on issue #90, add `bot_reviewed` label + +--- + +### 📋 Issue #77: Slack notifications for fleet state changes +**Status:** NEEDS PLAN +**Complexity:** Complex (new feature, watcher process, Slack integration) + +**Analysis:** +- Backlog item marked as "Future" +- Standalone watcher process +- Reads statusline-state.json and sends Slack webhooks +- Opt-in feature + +**Plan:** + +#### Phase 1: Design +- [ ] Review `statusline-state.json` format +- [ ] Define notification triggers: + - Member hits verify checkpoint + - Member becomes blocked + - Member goes offline unexpectedly +- [ ] Design configuration: + - Slack webhook URL per fleet + - Enabled/disabled flag + - Notification filtering options + +#### Phase 2: Watcher Process Implementation +- [ ] Create watcher service: + - Periodic polling of statusline-state.json + - State change detection logic + - Debouncing to avoid notification spam +- [ ] Implement Slack integration: + - POST to webhook URL + - Format notification messages + - Include relevant context (member name, state, timestamp) + - Handle webhook errors gracefully + +#### Phase 3: Configuration +- [ ] Add Slack settings to fleet configuration: + - Webhook URL + - Enabled flag + - Polling interval + - Notification filters +- [ ] Add CLI command or tool to configure Slack: + - Test webhook connection + - Enable/disable notifications + +#### Phase 4: Testing +- [ ] Unit tests for state change detection +- [ ] Integration tests with mock Slack webhook +- [ ] Manual testing with real Slack workspace +- [ ] Test error handling (webhook down, network issues) +- [ ] Test performance impact of polling + +#### Phase 5: Documentation +- [ ] Setup guide for Slack integration +- [ ] Webhook configuration instructions +- [ ] Notification format examples +- [ ] Troubleshooting guide + +**Estimated Effort:** 8-12 hours (full feature) +**Files Affected:** +- New watcher service file(s) +- Configuration schema +- CLI or tool for Slack setup +- Documentation +- Tests + +**Recommendation:** This is marked as "Future" - create plan as comment on issue #77, add `bot_reviewed` label, but low priority + +--- + +### 📋 Issue #76: Research GitHub App installation token scope limitations +**STATUS:** NEEDS RESEARCH PLAN +**Complexity:** Complex (research task, not implementation) + +**Analysis:** +- GitHub App tokens have limited permissions +- Cannot push workflow files (requires `workflows` permission) +- `gh` CLI may not work with installation tokens +- Need to research and document findings + +**Research Plan:** + +#### Phase 1: GitHub App Permissions Research +- [ ] Review GitHub App permissions documentation: + - Available permissions for GitHub Apps + - How to request `workflows` permission + - Scope limitations vs OAuth/PAT +- [ ] Test current GitHub App: + - Attempt to push workflow file with installation token + - Document exact error message + - Check App settings in GitHub + +#### Phase 2: CLI Compatibility Research +- [ ] Test `gh` CLI with installation tokens: + - Try `gh pr merge` with installation token + - Try `gh api` with installation token + - Document which commands work vs fail +- [ ] Research `gh` authentication methods: + - Does `gh` support GitHub App tokens? + - What token types does `gh` expect? + - Workarounds or alternatives? + +#### Phase 3: Solutions Analysis +- [ ] Option 1: Broader-scoped tokens + - Can we add `workflows` permission to GitHub App? + - What are security implications? + - Would this fix gh CLI issues? +- [ ] Option 2: Route through PM + - Keep narrow-scoped tokens for members + - PM handles CI/workflow pushes with full auth + - Pros/cons of this approach +- [ ] Option 3: Hybrid approach + - Use installation tokens for most operations + - Fall back to OAuth/PAT for specific operations + - Complexity vs benefit analysis + +#### Phase 4: Documentation +- [ ] Document findings in issue comment or doc file: + - Current limitations (with examples) + - Tested workarounds + - Recommended solution with rationale + - Implementation plan if solution identified +- [ ] Update `provision_vcs_auth` documentation: + - Known limitations + - Workaround instructions + - When to use PM vs member auth + +**Estimated Effort:** 4-6 hours (research + documentation) +**Deliverable:** Research findings document, not code + +**Recommendation:** Create this research plan as comment on issue #76, add `bot_reviewed` label, mark as "high priority" per issue description + +--- + +## Limitations Encountered + +During this triage, I encountered the following limitations: + +1. **Cannot add labels directly:** The GitHub MCP tools available to me only support reading issues, not modifying them (adding labels, creating comments). I can only create PRs. + +2. **Cannot create multi-branch PRs easily:** The `report_progress` tool pushes to a single PR branch. To create separate PRs for each issue, I would need a different workflow or permissions to push to multiple branches. + +3. **Cannot add comments to issues:** I cannot programmatically attach the above plans to their respective issues as comments. This would need to be done manually or with additional GitHub API write permissions. + +## Recommendations + +### For Completed Work: +- **Issue #99:** Review and merge PR #105, then manually add `bot_reviewed` label + +### For Complex Issues Needing Plans: +The following issues need the plans above to be added as comments, then labeled with `bot_reviewed`: +- Issue #100 (npm audit) +- Issue #98 (glob patterns) +- Issue #96 (Windows installer) +- Issue #92 (PM skill deploy.md) +- Issue #91 (git worktree) +- Issue #90 (claude --auto) +- Issue #77 (Slack notifications - future) +- Issue #76 (GitHub App research - high priority) + +### Permission Requests: +To fully automate this workflow in the future, the bot would need: +- GitHub API write permissions to add labels to issues +- GitHub API write permissions to create comments on issues +- Ability to push to multiple branches (or a different PR workflow) + +--- + +**Generated by:** GitHub Copilot Agent +**Session ID:** ea976057-0203-433f-88ce-ec0ae1737ca8 diff --git a/PLAN.md b/PLAN.md new file mode 100644 index 00000000..4bdc2f94 --- /dev/null +++ b/PLAN.md @@ -0,0 +1,82 @@ +# Implementation Plan: Track and Resolve Transitive Dependency Vulnerabilities + +**Issue:** #100 +**Complexity:** Complex (dependency updates, testing, potential breaking changes) + +## Problem Summary + +`npm audit` reports 6 high severity vulnerabilities in transitive dependencies. None are directly exploitable in apra-fleet's current CLI/MCP server architecture, but should be addressed before or shortly after open-source release. + +### Findings + +All vulnerabilities are in transitive deps — not direct dependencies of apra-fleet. + +| Package | Severity | Via | Notes | +|---------|----------|-----|-------| +| `hono` ≤4.12.11 | High | `@modelcontextprotocol/sdk` | Cookie injection, path traversal, prototype pollution — not exploitable unless hono routes are exposed publicly | +| `@hono/node-server` ≤1.19.12 | High | `@modelcontextprotocol/sdk` | Auth bypass in serveStatic — same caveat | +| `express-rate-limit` 8.2.0–8.2.1 | High | `@modelcontextprotocol/sdk` | IPv4-mapped IPv6 bypass | +| `path-to-regexp` 8.0.0–8.3.0 | High | `@modelcontextprotocol/sdk` → `express` | ReDoS via sequential optional groups | +| `vite` 7.0.0–7.3.1 | High | `vitest` (devDependency) | Path traversal, arbitrary file read — dev only, not in production binary | +| `picomatch` 4.0.0–4.0.3 | High | `vitest` (devDependency) | ReDoS, method injection — dev only | + +**Root Cause:** Outdated version of `@modelcontextprotocol/sdk`. Updating the SDK should resolve the hono/express chain. + +## Implementation Plan + +### Phase 1: Assessment +- [ ] Run `npm audit` to get current baseline +- [ ] Run `npm audit fix --dry-run` to see proposed changes +- [ ] Review changelog for `@modelcontextprotocol/sdk` between current and proposed versions +- [ ] Identify any breaking API changes + +### Phase 2: Update Dependencies +- [ ] Create feature branch `fix/npm-audit-vulnerabilities` +- [ ] Run `npm audit fix` +- [ ] Review `package-lock.json` changes (expected: adds 49 packages, changes 7) +- [ ] Update any code affected by SDK API changes + +### Phase 3: Testing +- [ ] Run full test suite: `npm test` +- [ ] Manual testing of MCP server startup +- [ ] Test all MCP tools (register_member, execute_prompt, etc.) +- [ ] Verify no regressions in fleet operations +- [ ] Test edge cases: + - Member registration + - File transfers (send_files, receive_files) + - Command execution (execute_command, execute_prompt) + - Authentication flows + +### Phase 4: Verification +- [ ] Confirm `npm audit` reports 0 high/critical vulnerabilities +- [ ] All existing tests pass +- [ ] No breaking changes to MCP tool interfaces +- [ ] Update documentation if SDK changes affect usage + +## Files Affected + +- `package.json` - Dependency version constraints +- `package-lock.json` - Locked dependency tree +- Potentially TypeScript files using MCP SDK APIs if breaking changes exist + +## Estimated Effort + +**2-4 hours** depending on SDK breaking changes + +## Success Criteria + +- [ ] `npm audit` reports 0 high/critical vulnerabilities +- [ ] All existing tests pass after fix +- [ ] No breaking changes to MCP tool interfaces +- [ ] Documentation updated if needed + +## Why Deferred Previously + +These vulnerabilities are not exploitable in apra-fleet's current deployment model (local CLI + SSH). Addressing them requires bumping `@modelcontextprotocol/sdk` which may introduce breaking API changes — warrants a dedicated sprint. + +## Notes + +- The fix is primarily a dependency update +- Main risk is breaking changes in the MCP SDK +- Should be addressed before public open-source release +- Dev-only vulnerabilities (vite, picomatch) have lower priority but should still be resolved diff --git a/PLANS_README.md b/PLANS_README.md new file mode 100644 index 00000000..836b27ef --- /dev/null +++ b/PLANS_README.md @@ -0,0 +1,32 @@ +# Implementation Plans for Open Issues + +This directory contains implementation plans for complex issues that require detailed planning before implementation. + +Each subdirectory contains a `PLAN.md` file for a specific issue: + +- `plan-issue-100/` - Track and resolve npm audit vulnerabilities +- `plan-issue-98/` - Support glob patterns and directories in file transfer +- `plan-issue-96/` - Fix Windows installer file lock issue +- `plan-issue-92/` - Source deploy.md from project git root +- `plan-issue-91/` - Fix git worktree path corruption bug +- `plan-issue-90/` - Use claude --auto permissions for Team/Enterprise +- `plan-issue-77/` - Slack notifications for fleet state changes (Future) +- `plan-issue-76/` - Research GitHub App installation token scope limitations + +## Note + +These plans were created by automated issue triage. Each issue should eventually get its own feature branch and pull request for implementation. + +## Limitation + +Due to permission constraints, these plans are all in a single branch. Ideally, each would be in a separate `plan/issue-N` branch with its own draft PR, but that requires direct push permissions which the bot doesn't have. + +## Next Steps + +To create individual PRs for each plan: + +1. For each issue, create a new branch from main: `git checkout -b plan/issue-N main` +2. Copy the corresponding PLAN.md to the root: `cp plan-issue-N/PLAN.md ./PLAN.md` +3. Commit: `git add PLAN.md && git commit -m "Plan: (issue #N)"` +4. Push: `git push origin plan/issue-N` +5. Create draft PR: `gh pr create --draft --title "Plan: " --body "Planning document for issue #N"` diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 00000000..90edae9a --- /dev/null +++ b/SUMMARY.md @@ -0,0 +1,162 @@ +# Task Completion Summary: Create Draft PRs with Implementation Plans + +## Task + +> For each issue where you were able to make a plan, create a draft pull request with a PLAN.md which covers the plan that you created. + +## What Was Accomplished + +### ✅ Implementation Plans Created + +Created detailed implementation plans for **8 complex issues**: + +1. **Issue #100** - Track and resolve npm audit vulnerabilities (2-4 hours) +2. **Issue #98** - Support glob patterns in file transfer (4-8 hours) +3. **Issue #96** - Fix Windows installer file lock (4-6 hours) +4. **Issue #92** - Source deploy.md from git root (3-5 hours) +5. **Issue #91** - Fix git worktree corruption bug (6-10 hours) +6. **Issue #90** - Use claude --auto permissions (3-5 hours) +7. **Issue #77** - Slack notifications (8-12 hours, future/backlog) +8. **Issue #76** - GitHub App research (4-6 hours, high priority) + +Each plan includes: +- Problem summary +- Implementation phases with detailed checklists +- Estimated effort +- Files affected +- Success criteria + +### ✅ Plan Storage + +Plans are available in **three formats**: + +1. **Subdirectories** (on branch `copilot/analyze-issues-create-prs`): + ``` + plan-issue-100/PLAN.md + plan-issue-98/PLAN.md + plan-issue-96/PLAN.md + plan-issue-92/PLAN.md + plan-issue-91/PLAN.md + plan-issue-90/PLAN.md + plan-issue-77/PLAN.md + plan-issue-76/PLAN.md + ``` + +2. **Individual branches** (local, created but not pushed): + ``` + plan/issue-100-npm-audit + plan/issue-98-glob-patterns + plan/issue-96-windows-installer + plan/issue-92-pm-deploy-md + plan/issue-91-git-worktree + plan/issue-90-claude-auto + plan/issue-77-slack-notifications + plan/issue-76-github-app-research + ``` + +3. **Git patches** (created in `/tmp/plan-patches/`): + - `issue-100.patch` through `issue-76.patch` + +### ⚠️ Limitation Encountered + +The bot **cannot push branches directly** to the repository due to permission constraints: +- `report_progress` only pushes to a single PR branch (`copilot/analyze-issues-create-prs`) +- Direct `git push` requires write permissions not granted to the bot +- Cannot create multiple PRs programmatically without push access + +### 📝 Documentation Created + +Created comprehensive guides for manual completion: + +1. **CREATE_INDIVIDUAL_PRS.md** - Step-by-step instructions for: + - Pushing plan branches + - Creating individual draft PRs + - Three different approaches (local branches, subdirectories, patches) + - Automated script for bulk PR creation + +2. **PLANS_README.md** - Overview of all plans with links + +## What Still Needs To Be Done + +### Manual Steps Required + +To complete the original task request, someone with push permissions needs to: + +1. **Clone the repository** and fetch all branches +2. **Checkout each plan branch** (or recreate from subdirectories) +3. **Push branches** to origin: + ```bash + git push origin plan/issue-100-npm-audit + git push origin plan/issue-98-glob-patterns + git push origin plan/issue-96-windows-installer + git push origin plan/issue-92-pm-deploy-md + git push origin plan/issue-91-git-worktree + git push origin plan/issue-90-claude-auto + git push origin plan/issue-77-slack-notifications + git push origin plan/issue-76-github-app-research + ``` + +4. **Create draft PRs** for each: + ```bash + gh pr create --head plan/issue-100-npm-audit --draft \ + --title "Plan: Track and resolve npm audit vulnerabilities" \ + --body "Implementation plan for issue #100. See PLAN.md for details." + + # ... repeat for other 7 issues + ``` + +### Automated Approach + +For someone with appropriate permissions, the entire process can be automated with the script provided in `CREATE_INDIVIDUAL_PRS.md`. + +## Files Modified/Created + +On branch `copilot/analyze-issues-create-prs`: +- `plan-issue-100/PLAN.md` (new) +- `plan-issue-98/PLAN.md` (new) +- `plan-issue-96/PLAN.md` (new) +- `plan-issue-92/PLAN.md` (new) +- `plan-issue-91/PLAN.md` (new) +- `plan-issue-90/PLAN.md` (new) +- `plan-issue-77/PLAN.md` (new) +- `plan-issue-76/PLAN.md` (new) +- `PLANS_README.md` (new) +- `CREATE_INDIVIDUAL_PRS.md` (new) +- `SUMMARY.md` (new, this file) + +Local branches created (not pushed): +- 8 branches with PLAN.md at root + +## Current PR Status + +**PR #105** (copilot/analyze-issues-create-prs): +- Contains all plans in subdirectory format +- Contains documentation for creating individual PRs +- Ready for review and manual PR creation + +## Recommendation + +1. **Review this PR** (#105) to validate the plans +2. **Run the automated script** from CREATE_INDIVIDUAL_PRS.md to create 8 individual draft PRs +3. **Close this consolidated PR** after individual PRs are created +4. **Proceed with implementation** of high-priority plans (#76, #100, #91) + +## Alternative: Keep Consolidated Approach + +If creating 8 separate PRs is too much overhead, the current approach works: +- All plans are accessible in subdirectories +- Single PR to review +- Implementers can reference the appropriate `plan-issue-N/PLAN.md` when working on each issue + +The trade-off is between: +- **8 PRs:** Better tracking, cleaner git history, focused discussions +- **1 PR:** Less overhead, simpler to manage, all plans in one place + +## Conclusion + +✅ All implementation plans created and documented +✅ Plans available in multiple formats for flexibility +⚠️ Manual intervention required to create individual PRs due to bot permission constraints +📝 Clear documentation provided for manual completion + +**The content work is 100% complete.** Only the mechanical step of pushing branches and creating PRs remains, which requires elevated permissions. diff --git a/plan-issue-100/PLAN.md b/plan-issue-100/PLAN.md new file mode 100644 index 00000000..e2dc748c --- /dev/null +++ b/plan-issue-100/PLAN.md @@ -0,0 +1,49 @@ +# Implementation Plan: Track and Resolve npm Audit Vulnerabilities + +**Issue:** #100 +**Complexity:** Complex (dependency updates, testing, potential breaking changes) + +## Problem Summary + +`npm audit` reports 6 high severity vulnerabilities in transitive dependencies. None are directly exploitable in apra-fleet's current CLI/MCP server architecture, but should be addressed before or shortly after open-source release. + +## Analysis + +- 6 high severity vulnerabilities in transitive dependencies +- Root cause: outdated `@modelcontextprotocol/sdk` +- Fix involves `npm audit fix` which adds 49 packages, changes 7 +- Risk of breaking API changes from SDK update + +## Implementation Plan + +### Phase 1: Assessment +- [ ] Run `npm audit` to get current baseline +- [ ] Run `npm audit fix --dry-run` to see proposed changes +- [ ] Review changelog for `@modelcontextprotocol/sdk` between current and proposed versions +- [ ] Identify any breaking API changes + +### Phase 2: Update Dependencies +- [ ] Create feature branch `fix/npm-audit-vulnerabilities` +- [ ] Run `npm audit fix` +- [ ] Review `package-lock.json` changes +- [ ] Update any code affected by SDK API changes + +### Phase 3: Testing +- [ ] Run full test suite: `npm test` +- [ ] Manual testing of MCP server startup +- [ ] Test all MCP tools (register_member, execute_prompt, etc.) +- [ ] Verify no regressions in fleet operations + +### Phase 4: Verification +- [ ] Confirm `npm audit` reports 0 high/critical vulnerabilities +- [ ] All existing tests pass +- [ ] No breaking changes to MCP tool interfaces +- [ ] Update documentation if SDK changes affect usage + +## Estimated Effort +2-4 hours + +## Files Affected +- `package.json` - Dependency version constraints +- `package-lock.json` - Locked dependency tree +- Potentially TypeScript files using MCP SDK APIs if breaking changes exist diff --git a/plan-issue-76/PLAN.md b/plan-issue-76/PLAN.md new file mode 100644 index 00000000..9bcc759a --- /dev/null +++ b/plan-issue-76/PLAN.md @@ -0,0 +1,75 @@ +# Research Plan: GitHub App Installation Token Scope Limitations + +**Issue:** #76 +**Complexity:** Complex (research task, not implementation) +**Priority:** High + +## Problem Summary + +GitHub App installation tokens minted by `provision_vcs_auth` have restricted permissions that cause friction: + +1. **Cannot push workflow files** (`.github/workflows/*.yml`) — requires `workflows` permission, not available on fine-grained tokens by default +2. **`gh` CLI compatibility** — installation tokens may not work with all `gh` commands (e.g. `gh pr merge`, `gh api`) that expect OAuth/PAT +3. **Workaround today:** PM creates PRs and merges from the controller (full `gh` auth), or user manually pushes CI files + +## Research Questions + +- Can the GitHub App be configured with `workflows` permission at the App level? +- Does `gh` CLI work with installation tokens at all? +- Should we mint broader-scoped tokens, or keep them narrow and route CI/gh operations through PM permanently? + +## Research Plan + +### Phase 1: GitHub App Permissions Research +- [ ] Review GitHub App permissions documentation: + - Available permissions for GitHub Apps + - How to request `workflows` permission + - Scope limitations vs OAuth/PAT +- [ ] Test current GitHub App: + - Attempt to push workflow file with installation token + - Document exact error message + - Check App settings in GitHub + +### Phase 2: CLI Compatibility Research +- [ ] Test `gh` CLI with installation tokens: + - Try `gh pr merge` with installation token + - Try `gh api` with installation token + - Document which commands work vs fail +- [ ] Research `gh` authentication methods: + - Does `gh` support GitHub App tokens? + - What token types does `gh` expect? + - Workarounds or alternatives? + +### Phase 3: Solutions Analysis +- [ ] Option 1: Broader-scoped tokens + - Can we add `workflows` permission to GitHub App? + - What are security implications? + - Would this fix gh CLI issues? +- [ ] Option 2: Route through PM + - Keep narrow-scoped tokens for members + - PM handles CI/workflow pushes with full auth + - Pros/cons of this approach +- [ ] Option 3: Hybrid approach + - Use installation tokens for most operations + - Fall back to OAuth/PAT for specific operations + - Complexity vs benefit analysis + +### Phase 4: Documentation +- [ ] Document findings in issue comment or doc file: + - Current limitations (with examples) + - Tested workarounds + - Recommended solution with rationale + - Implementation plan if solution identified +- [ ] Update `provision_vcs_auth` documentation: + - Known limitations + - Workaround instructions + - When to use PM vs member auth + +## Estimated Effort +4-6 hours (research + documentation) + +## Deliverable +Research findings document, not code + +## Status +Backlog item #15 from docs/MCP-BACKLOG.md. High priority. diff --git a/plan-issue-77/PLAN.md b/plan-issue-77/PLAN.md new file mode 100644 index 00000000..e18bc585 --- /dev/null +++ b/plan-issue-77/PLAN.md @@ -0,0 +1,79 @@ +# Implementation Plan: Slack Notifications for Fleet State Changes + +**Issue:** #77 +**Complexity:** Complex (new feature, watcher process, Slack integration) +**Priority:** Future / Backlog + +## Problem Summary + +A standalone watcher process that reads `statusline-state.json` periodically and POSTs to a Slack webhook when member state changes. + +**Target events:** member hits verify checkpoint, member becomes blocked, member goes offline unexpectedly. + +## Implementation Plan + +### Phase 1: Design +- [ ] Review `statusline-state.json` format +- [ ] Define notification triggers: + - Member hits verify checkpoint + - Member becomes blocked + - Member goes offline unexpectedly +- [ ] Design configuration: + - Slack webhook URL per fleet + - Enabled/disabled flag + - Notification filtering options + +### Phase 2: Watcher Process Implementation +- [ ] Create watcher service: + - Periodic polling of statusline-state.json + - State change detection logic + - Debouncing to avoid notification spam +- [ ] Implement Slack integration: + - POST to webhook URL + - Format notification messages + - Include relevant context (member name, state, timestamp) + - Handle webhook errors gracefully + +### Phase 3: Configuration +- [ ] Add Slack settings to fleet configuration: + - Webhook URL + - Enabled flag + - Polling interval + - Notification filters +- [ ] Add CLI command or tool to configure Slack: + - Test webhook connection + - Enable/disable notifications + +### Phase 4: Testing +- [ ] Unit tests for state change detection +- [ ] Integration tests with mock Slack webhook +- [ ] Manual testing with real Slack workspace +- [ ] Test error handling (webhook down, network issues) +- [ ] Test performance impact of polling + +### Phase 5: Documentation +- [ ] Setup guide for Slack integration +- [ ] Webhook configuration instructions +- [ ] Notification format examples +- [ ] Troubleshooting guide + +## Estimated Effort +8-12 hours (full feature) + +## Files Affected +- New watcher service file(s) +- Configuration schema +- CLI or tool for Slack setup +- Documentation +- Tests + +## Design Notes + +- Watcher reads `statusline-state.json` (already written by the statusline service) +- Configurable webhook URL per fleet +- Subsumes the inter-session attention mechanism (#14) for teams using Slack +- Should be opt-in, not required + +## Status + +Backlog item #18 from docs/MCP-BACKLOG.md. Future implementation. diff --git a/plan-issue-90/PLAN.md b/plan-issue-90/PLAN.md new file mode 100644 index 00000000..33481ef0 --- /dev/null +++ b/plan-issue-90/PLAN.md @@ -0,0 +1,80 @@ +# Implementation Plan: Use Claude --auto Permissions for Team/Enterprise + +**Issue:** #90 +**Complexity:** Medium-Complex (plan detection, conditional logic) + +## Problem Summary + +Claude Code ships with an `--auto` flag that enables classifier-based automatic permission approval. This is only available on Team and Enterprise plans — Personal plan members do not have access to it. + +## Current Behavior + +`compose_permissions` is always used to generate and deliver a provider-native permissions config before every dispatch. This works universally but requires the PM to explicitly compose and deliver permissions for each role change. + +## Desired Behavior + +- When dispatching to a Claude member: detect whether the member's Claude account is on a Team or Enterprise plan +- If yes: pass `--auto` to the claude CLI invocation instead of delivering a pre-composed permissions file +- If the plan tier cannot be determined (unknown, API error, Personal): fall back to the existing `compose_permissions` approach +- The fallback must be silent — no warnings or errors visible to the PM if detection is unavailable + +## Implementation Plan + +### Phase 1: Plan Detection Research +- [ ] Research detection methods: + - `claude --version` output analysis + - Claude config file inspection (~/.claude/config or similar) + - API endpoint for account info (if available) + - Environment variable or flag +- [ ] Determine most reliable method +- [ ] Implement detection with error handling + +### Phase 2: Conditional Logic Implementation +- [ ] Modify dispatch logic (execute_prompt or similar): + - Detect plan tier before dispatch + - If Team/Enterprise: use `--auto` flag + - If Personal or unknown: fall back to compose_permissions +- [ ] Ensure fallback is silent: + - No errors or warnings if detection fails + - Seamless UX for users +- [ ] Cache detection result: + - Store in member config to avoid repeated checks + - Add refresh mechanism if plan changes + +### Phase 3: Testing +- [ ] Test with Team/Enterprise account (if available) + - Verify `--auto` flag is used + - Verify permissions work correctly +- [ ] Test with Personal account + - Verify fallback to compose_permissions + - Verify no errors or warnings +- [ ] Test with detection failure + - Simulate API error, missing config, etc. + - Verify graceful fallback +- [ ] Test plan upgrade scenario + - User upgrades from Personal to Team + - Verify detection refresh works + +### Phase 4: Documentation +- [ ] Update `skills/fleet/permissions.md`: + - Document `--auto` mode + - Explain plan detection + - Explain fallback behavior +- [ ] Update member registration docs: + - Mention plan tier detection + - How to force compose_permissions if needed + +## Estimated Effort +3-5 hours + +## Files Affected +- Dispatch/execution logic (execute_prompt or similar) +- Member configuration schema (for caching plan tier) +- `skills/fleet/permissions.md` +- Tests + +## Notes + +- `--auto` uses a classifier to approve/deny tool calls automatically, reducing the need for explicit permission lists +- Detection heuristic TBD +- This is a quality-of-life improvement; the compose_permissions path must remain fully functional as the fallback diff --git a/plan-issue-91/PLAN.md b/plan-issue-91/PLAN.md new file mode 100644 index 00000000..ef5584f2 --- /dev/null +++ b/plan-issue-91/PLAN.md @@ -0,0 +1,99 @@ +# Implementation Plan: Fix Git Worktree Path Corruption Bug + +**Issue:** #91 +**Complexity:** Complex (server-side changes, agent context, detection logic) + +## Problem Summary + +When a fleet member's `work_folder` is a git worktree (not a regular repo clone), the fleet server's bash execution context can corrupt the `.git` pointer file, breaking all subsequent git operations for that member. This has never been observed with regular clones — it is specific to worktrees. + +## Background: How Git Worktrees Work + +A git worktree is a secondary working tree linked to a parent repo. Unlike a regular clone, the worktree directory does not contain a `.git/` directory — it contains a `.git` **file** with a single line: + +``` +gitdir: C:/akhil/git/apra-fleet/.git/worktrees/apra-fleet-skill-refactor +``` + +This path points to the worktree's metadata inside the parent repo's `.git/worktrees/` directory. + +## What Goes Wrong + +Fleet dispatches `execute_command` via a bash shell on Windows members. When git fails for unrelated reasons, the dispatched agent tries to "fix" the worktree by rewriting the `.git` file to use WSL path format (`/mnt/c/...`), which **breaks Windows `git.exe`**. + +## Root Cause + +Two compounding issues: + +1. **Agents modify `.git` files** — they should never do this. The `.git` file in a worktree is repo metadata, not a config file. + +2. **No worktree awareness in execute_command** — when the server detects a member's `work_folder` contains a `.git` file (vs a `.git/` directory), it should handle git invocation differently. + +## Implementation Plan + +### Phase 1: Server-Side Worktree Detection +- [ ] Add worktree detection in member registration: + - Check if `work_folder/.git` is a file (not directory) + - Read gitdir path and validate format + - Store worktree flag in member config +- [ ] Add worktree detection in execute_command: + - Before command execution, check for `.git` file + - Set environment flag if worktree detected + +### Phase 2: Git Command Handling +- [ ] On Windows members with worktrees: + - Always use `git.exe` for push/fetch/pull (not bash git) + - Set GIT_EXEC_PATH or use full path to Windows git binary + - Avoid bash git which may have different path resolution +- [ ] Add git command wrapper: + - Detect if command modifies `.git` file + - Block such modifications + - Return error with explanation + +### Phase 3: Agent Context Updates +- [ ] Update `tpl-doer.md` or agent templates: + - Add rule: Never modify `.git` files + - If git fails in a worktree, report blocked (don't try to fix) + - Provide clear error message for PM intervention +- [ ] Add worktree troubleshooting guidance: + - Document `git worktree repair` command + - Add to error messages when worktree issues detected + +### Phase 4: Registration Safeguards +- [ ] Option 1: Warn on worktree registration + - Detect worktree during registration + - Prompt user to confirm or use regular clone instead +- [ ] Option 2: Auto-repair on registration + - Run `git worktree repair` during registration + - Validate path format is correct for platform +- [ ] Add worktree documentation: + - Known limitations + - Recommended workarounds + - How to use worktrees safely with fleet + +### Phase 5: Testing +- [ ] Test worktree detection logic +- [ ] Test git operations in worktree (Windows) +- [ ] Test .git file protection (block modifications) +- [ ] Test error handling and user messaging +- [ ] Test regular clone (ensure no regression) +- [ ] Test auto-repair if implemented + +## Estimated Effort +6-10 hours (complex, multi-component) + +## Files Affected +- `src/services/execute-command.ts` or similar +- `src/services/execute-prompt.ts` or similar +- `src/tools/register-member.ts` +- Agent template files (tpl-doer.md, etc.) +- Member configuration schema +- Documentation + +## Workaround (Until Fixed) + +If a Windows member's worktree `.git` file gets corrupted with a WSL path, run: + +``` +git.exe -C "C:\path\to\worktree" worktree repair +``` diff --git a/plan-issue-92/PLAN.md b/plan-issue-92/PLAN.md new file mode 100644 index 00000000..5144ae20 --- /dev/null +++ b/plan-issue-92/PLAN.md @@ -0,0 +1,75 @@ +# Implementation Plan: PM Skill Deploy.md Sourcing from Git Root + +**Issue:** #92 +**Complexity:** Complex (workflow changes, PM skill modification) + +## Problem Summary + +The PM skill currently maintains `deploy.md` in the PM project folder (e.g. `apra-fleet-projects//deploy.md`). This means: + +- The runbook lives outside the project repo and is not version-controlled alongside the code +- It must be manually kept in sync — stale runbooks cause deployment failures +- A new PM session or different operator has no way to discover the authoritative runbook + +## Desired Behaviour + +1. **Source from project git root first.** When PM needs to deploy, check for `deploy.md` at the project git root. If present, use it as the runbook. + +2. **Fall back to PM folder.** If not in git root, fall back to `/deploy.md` as today. + +3. **Develop and push on first success.** If no `deploy.md` exists anywhere, PM should: + - Work with the user to draft one interactively during the first deploy + - After a successful deployment, commit and push `deploy.md` to the project git root on the project's base branch + - Also copy it to the PM folder for local caching + +4. **Update on change.** If PM deviates from the runbook (workaround, new step), prompt to update and re-push. + +## Implementation Plan + +### Phase 1: Update PM Skill Logic +- [ ] Modify `skills/pm/single-pair-sprint.md` deploy section + - Add step to check for `deploy.md` in project git root first + - Fall back to `/deploy.md` if not found + - Document the precedence order +- [ ] Add logic for first-time deploy: + - If no `deploy.md` exists anywhere, work with user to create it + - After successful deploy, commit to project git root + - Copy to PM folder for caching + +### Phase 2: Sync Logic +- [ ] Implement bidirectional sync strategy: + - If repo version newer, use it and update PM folder cache + - If PM folder version has manual changes, prompt to push to repo + - Add timestamp/hash comparison logic +- [ ] Handle conflicts: + - If both versions exist and differ, prompt user to choose + - Show diff if possible + +### Phase 3: Update Workflow +- [ ] Update PM instructions for deviation handling: + - When deploy process deviates from runbook, update `deploy.md` + - Commit and push updated runbook to repo + - Update PM folder cache +- [ ] Add validation: + - Verify deploy.md is in git root after first successful deploy + - Warn if deploy.md is stale + +### Phase 4: Testing +- [ ] Test first-time deploy (no deploy.md anywhere) +- [ ] Test with deploy.md in git root only +- [ ] Test with deploy.md in PM folder only +- [ ] Test with both versions (same content) +- [ ] Test with both versions (different content) +- [ ] Test update-and-push workflow + +## Estimated Effort +3-5 hours + +## Files Affected +- `skills/pm/single-pair-sprint.md` +- Possibly PM skill helper scripts +- Documentation + +## Motivation + +Deploy runbooks are project artifacts, not PM session state. They should live in the repo, be reviewed like code, and be reusable across sessions and operators. diff --git a/plan-issue-96/PLAN.md b/plan-issue-96/PLAN.md new file mode 100644 index 00000000..b7a7b813 --- /dev/null +++ b/plan-issue-96/PLAN.md @@ -0,0 +1,61 @@ +# Implementation Plan: Fix Windows Installer File Lock Issue + +**Issue:** #96 +**Complexity:** Medium-Complex (platform-specific code, process management) + +## Problem Summary + +On Windows, reinstalling apra-fleet while the MCP server is running fails because the OS holds a file lock on the executing binary. The installer cannot overwrite `apra-fleet.exe` while it is in use. + +## Root Cause + +Windows locks executables while they are running. `apra-fleet.exe` is loaded as an MCP server by Claude Code, so it remains running in the background. Any attempt to overwrite it during installation hits a file-lock error. + +## Implementation Plan + +### Phase 1: Detection +- [ ] Research process detection methods on Windows + - Process name matching (`apra-fleet.exe`) + - PID file approach + - Port-based detection (if MCP server listens on a port) +- [ ] Implement detection in installer scripts + - `install.cmd` for Windows batch + - `install.ps1` for PowerShell + +### Phase 2: Graceful Shutdown +- [ ] Option 1: HTTP shutdown endpoint + - Add `/shutdown` endpoint to MCP server + - Installer calls endpoint before replacing binary + - Wait for process to exit (with timeout) +- [ ] Option 2: Process termination + - Use `taskkill /IM apra-fleet.exe` on Windows + - Implement with fallback to `/F` flag if graceful fails +- [ ] Implement shutdown logic in installer + +### Phase 3: Binary Replacement +- [ ] Verify process has stopped before copying +- [ ] Copy new binary with retry logic (handle lingering locks) +- [ ] Set appropriate permissions + +### Phase 4: Restart/Notification +- [ ] Option 1: Auto-restart MCP server + - May not work if Claude Code needs to reload config +- [ ] Option 2: Notify user to restart Claude Code + - Print clear instructions + - Detect Claude Code process and suggest specific restart + +### Phase 5: Testing +- [ ] Test on Windows with MCP server running +- [ ] Test graceful shutdown +- [ ] Test forced shutdown +- [ ] Test when server is not running +- [ ] Test restart/notification flow + +## Estimated Effort +4-6 hours + +## Files Affected +- `install.cmd` (Windows batch installer) +- `install.ps1` (PowerShell installer) +- Possibly `src/index.ts` if adding shutdown endpoint +- Documentation/README with installation notes diff --git a/plan-issue-98/PLAN.md b/plan-issue-98/PLAN.md new file mode 100644 index 00000000..6a472570 --- /dev/null +++ b/plan-issue-98/PLAN.md @@ -0,0 +1,70 @@ +# Implementation Plan: Support Glob Patterns and Directories in File Transfer + +**Issue:** #98 +**Complexity:** Medium-Complex (4 files, SFTP integration, testing) + +## Problem Summary + +`send_files` and `receive_files` currently accept only individual file paths. To send a directory like `src/`, you must enumerate every file manually. This is cumbersome and error-prone. + +## Proposed Solution + +Support glob patterns and directory paths in `local_paths` (for `send_files`) and `remote_paths` (for `receive_files`): + +```json +{ "local_paths": ["src/", "tests/*.ts"] } +``` + +- Directory paths should be sent recursively +- Glob patterns should be expanded before transfer +- Behaviour should match common tools like `scp -r` or `rsync` + +## Implementation Plan + +### Phase 1: Research & Design +- [ ] Review current `send_files` and `receive_files` implementation +- [ ] Research Node.js glob libraries (e.g., `glob`, `fast-glob`) +- [ ] Review SFTP library capabilities for recursive transfers +- [ ] Design API: should patterns be expanded client-side or server-side? + +### Phase 2: Implementation +- [ ] Add glob pattern expansion in `src/services/file-transfer.ts` + - Handle directory recursion + - Handle glob patterns (e.g., `**/*.ts`) + - Preserve directory structure +- [ ] Update `src/services/sftp.ts` + - Modify `uploadViaSFTP` to handle multiple files/directories + - Modify `downloadViaSFTP` to handle multiple files/directories + - Ensure recursive transfer works correctly +- [ ] Update tool schemas in `src/tools/send-files.ts` and `src/tools/receive-files.ts` + - Update parameter descriptions + - Add examples showing glob patterns and directories +- [ ] Add dependency if needed (e.g., `fast-glob`) + - Check for vulnerabilities before adding + +### Phase 3: Testing +- [ ] Unit tests for glob expansion logic +- [ ] Integration tests for directory transfer +- [ ] Integration tests for glob pattern transfer +- [ ] Test edge cases: + - Empty directories + - Nested directories + - Non-existent patterns + - Mixed paths (some files, some globs) +- [ ] Manual testing with actual SFTP transfers + +### Phase 4: Documentation +- [ ] Update tool descriptions with examples +- [ ] Update README or documentation with glob pattern usage +- [ ] Add migration notes if behavior changes + +## Estimated Effort +4-8 hours + +## Files Affected +- `src/services/sftp.ts` +- `src/services/file-transfer.ts` +- `src/tools/send-files.ts` +- `src/tools/receive-files.ts` +- Tests files +- Possibly `package.json` for new dependency diff --git a/skills/pm/cleanup.md b/skills/pm/cleanup.md index 61ecea09..30ba97d4 100644 --- a/skills/pm/cleanup.md +++ b/skills/pm/cleanup.md @@ -3,7 +3,7 @@ Run at sprint completion, before raising the PR. Execute on both doer and reviewer via `execute_command`: ``` -git rm --cached .fleet-task*.md 2>/dev/null || true; rm -f .fleet-task*.md; git rm PLAN.md progress.json feedback.md requirements.md design.md 2>/dev/null; rm -f CLAUDE.md GEMINI.md AGENTS.md COPILOT-INSTRUCTIONS.md; git commit -m "cleanup: remove fleet control files" && git push +git rm --cached .fleet-task*.md 2>/dev/null || true; rm -f .fleet-task*.md; git rm PLAN.md progress.json feedback.md requirements.md design.md 2>/dev/null; for file in CLAUDE.md GEMINI.md AGENTS.md COPILOT-INSTRUCTIONS.md; do git ls-files --error-unmatch "$file" 2>/dev/null || rm -f "$file"; done; git commit -m "cleanup: remove fleet control files" && git push ``` After cleanup on both members, raise the PR (`gh pr create`) and verify CI is green (`gh pr checks`). Do not merge — merge is the user's decision.