forge-workflow 0.0.1

package/docs/planning/PROGRESS.md

@@ -0,0 +1,396 @@
+# Project Progress
+
+## Current Focus
+<!-- What you're working on -->
+PR#52: Agent command parity design doc + ESLint worktrees fix. PR #50 (superpowers-gaps) and PR #51 (agent configs) both merged.
+
+### Chore: Agent Configs and Research Docs (2026-03-03)
+- **PR**: #51
+- **Branch**: chore/agent-configs-and-research-docs
+- **Description**: Committed agent permission configs for Aider, Codex CLI, OpenCode, and Cursor that were generated during prior sessions. Also committed research docs and a test suite v2 decision log.
+- **Deliverables**:
+  - **`.aider.conf.yml`**: Aider config — `yes-always: false`, `auto-accept-architect: true`, `auto-commits: false`, `read: AGENTS.md`
+  - **`.codex/config.toml`**: Codex CLI — `approval_policy = "on-request"`, `sandbox_mode = "workspace-write"`
+  - **`opencode.json`**: OpenCode permissions — allow/ask/deny tiers matching research doc classification
+  - **`.cursor/rules/permissions-guidance.mdc`**: Cursor YOLO mode allow/confirm/deny guidance
+  - **`docs/research/agent-permissions.md`**, **`agent-instructions-sync.md`**: Permission tier research and sync research
+  - **`docs/plans/2026-02-27-forge-test-suite-v2-decisions.md`**: Test suite v2 decision log
+- **Key Decisions**: `git rebase` → `ask`; `git push -f` added to deny; `auto-commits: false` to preserve commitlint hooks
+
+## Completed
+
+### PR5.7: Fix Skills Sync — All 11 Agents + Dual-Source Reading (2026-02-24)
+- **PR**: #46
+- **Beads**: forge-ab6 (closed)
+- **Research**: [docs/research/skills-restructure.md](../research/skills-restructure.md)
+- **Description**: After PR5.5 moved skills to `skills/` root, `bunx skills sync` stopped distributing to any agent. Fixed all 3 root causes with TDD.
+- **Root Causes Fixed**:
+  1. `AGENT_DEFINITIONS` had only 4 of 11 agents — expanded to all 11 (claude, kilocode, aider, roo, windsurf, opencode, antigravity added)
+  2. `getValidSkills()` only read from `.skills/` (empty) — now reads `skills/` root + `.skills/` with Map deduplication (`.skills/` wins)
+  3. copilot, roo, aider `plugin.json` had `skills: false` — all corrected to `true`
+- **Deliverables**:
+  - **`packages/skills/src/lib/agents.js`**: All 11 agents in `AGENT_DEFINITIONS`, all `enabled: true`; `configFile` passthrough for agents needing config-file updates
+  - **`packages/skills/src/commands/sync.js`**: Dual-source `getValidSkills()` via Map; `_collectSkillsFrom()` helper; `syncSkillsToAgents()` uses `skill.sourcePath`; new `updateAiderConfig()` writes `read:` entries to `.aider.conf.yml`
+  - **`lib/agents/copilot.plugin.json`**, **`roo.plugin.json`**, **`aider.plugin.json`**: Fixed `skills: false → true`
+  - **`.gitignore`**: Added `.agents/`, `.skills/`, `skills-lock.json`, all agent skill junction dirs (`.aider/skills/`, `.claude/skills/`, etc.)
+  - **`.claude/commands/sonarcloud.md`**: Updated skill reference path from `.claude/skills/sonarcloud/` → `skills/sonarcloud-analysis/`
+  - **12 new tests**: 7 agent detection tests + 5 sync validation tests (dual-source, dedup, claude/kilocode/aider sync)
+- **skills.sh mechanism understood**: Real files in `.agents/skills/`; agent dirs get OS-level junctions (not copies); junctions not committed to git
+- **Validation**: 105 pass in skills package, all CI checks green, Greptile 4/5 (Quality Gate passed), SonarCloud passed
+- **Files**: `packages/skills/src/lib/agents.js`, `packages/skills/src/commands/sync.js`, `packages/skills/test/agents.test.js`, `packages/skills/test/sync.test.js`, `lib/agents/copilot.plugin.json`, `lib/agents/roo.plugin.json`, `lib/agents/aider.plugin.json`, `.claude/commands/sonarcloud.md`, `.gitignore`
+
+### PR5.6: Cross-Platform Install Fixes (2026-02-23)
+- **PR**: #45
+- **Beads**: forge-k6p, forge-63c, forge-jxb, forge-92t, forge-4zz, forge-0xb, forge-cvr, forge-6q4 (all closed)
+- **Research**: [docs/research/dependency-chain.md](../research/dependency-chain.md)
+- **Description**: Fixed 8 cross-platform installation bugs covering Windows Beads EPERM bug, hardcoded `bun`/`bunx` in hooks and error messages, bash-only syntax in lefthook, and unpinned MCP versions
+- **Deliverables**:
+  - **Windows Beads install** (`bin/forge.js`): `installBeadsOnWindows()` uses PowerShell `irm install.ps1 | iex` on `win32` — bypasses `npm @beads/bd` EPERM postinstall bug (Issue #1031). All 3 install methods (global, local, method '2') detect win32 and delegate to `installBeadsOnWindows()`
+  - **`BEADS_INSTALL_PS1_URL` constant**: Centralised URL for PowerShell installer — used in `installBeadsOnWindows()`, error messages, and printed before execution for transparency
+  - **`autoInstallLefthook` PKG_MANAGER flags** (`bin/forge.js`): Removed hardcoded `bun add -d lefthook`; now uses `PKG_MANAGER` with correct flags per manager: `bun add -d`, `pnpm add -D`, `yarn add --dev`, `npm install --save-dev`
+  - **Error messages** (`bin/forge.js`): All "run manually" error messages now use `${PKG_MANAGER}` with correct flag instead of hardcoded `bun add -g`
+  - **OpenSpec/Skills messaging** (`bin/forge.js`): Shows explicit "not found — install with:" message when tools are not pre-installed (instead of silent skip)
+  - **Post-install verification** (`bin/forge.js`): `verifyToolInstall()` called after install, runs `bd version` to confirm tool is callable
+  - **Cross-platform lefthook hooks** (`lefthook.yml`): Replaced `bunx commitlint` → `npx --yes commitlint`, replaced `bunx eslint` + bash `if [$?]`/`command -v` syntax → `node scripts/lint.js` and `node scripts/test.js`
+  - **`scripts/lint.js`** (new): Cross-platform ESLint runner using `spawnSync('npx', ..., { shell: isWindows })` with `result.error` check
+  - **`scripts/test.js`** (new): Cross-platform test runner with `detectPackageManager()` lock file detection, `result.error` check
+  - **`.mcp.json.example`**: Pinned `context7-mcp@2` and `grep_app_mcp@1` instead of `@latest`
+  - **22 tests** (`test/cross-platform-install.test.js`): Source-inspection tests covering all 8 beads issues (forge-k6p through forge-6q4)
+- **Impact**: Forge `setup` command now works on Windows, npm/pnpm/yarn users, and any CI environment — not just bun/macOS/Linux
+- **Files**: `bin/forge.js`, `lefthook.yml`, `scripts/lint.js` (new), `scripts/test.js` (new), `test/cross-platform-install.test.js` (new), `.mcp.json.example`, `docs/research/dependency-chain.md` (new)
+- **Validation**: 22 new tests, 997+ passing total, all 26 CI checks passing (Windows, macOS, Linux × Node 20/22), Greptile Quality Gate PASSED, SonarCloud PASSED, CodeQL PASSED
+- **Security**: OWASP Top 10 reviewed, `BEADS_INSTALL_PS1_URL` printed before PowerShell execution for transparency, `spawnSync` uses `result.error` check (no silent failures), no shell injection (explicit args arrays)
+
+### PR5.5: Skills Restructure for skills.sh (2026-02-23)
+- **PR**: #43
+- **Beads**: forge-qst (closed)
+- **Research**: [docs/research/skills-restructure.md](../research/skills-restructure.md)
+- **Description**: Migrated skills to `skills/` (repo root, skills.sh standard), split monolithic `parallel-ai` into 4 focused curl-based skills, added dual CLI/curl install paths in catalog and `forge recommend` output, removed legacy `.claude/skills/` directories
+- **Deliverables**:
+  - **skills/ directory** (6 skills, downloadable on-demand via `npx skills add harshanandak/forge --skill <name>`):
+    - `parallel-web-search` — curl-based Parallel AI Search API
+    - `parallel-web-extract` — curl-based Parallel AI Extract API
+    - `parallel-deep-research` — curl-based Parallel AI Task API (pro/ultra processors)
+    - `parallel-data-enrichment` — curl-based Parallel AI Task API (core/base processors)
+    - `sonarcloud-analysis` — migrated from `.claude/skills/sonarcloud/` with corrected name
+    - `citation-standards` — new internal rule skill for research docs
+  - **Catalog changes** (lib/plugin-catalog.js):
+    - `parallel-web-search` replaces `parallel-ai` — dual install paths (`install.cmd` CLI + `install.cmdCurl` curl)
+    - `sonarcloud-analysis` replaces `sonarcloud`
+    - `parallel-cli` added to PREREQUISITES registry
+  - **Recommend output** (lib/commands/recommend.js):
+    - Shows "CLI (recommended)" and "Curl (no install)" options for dual-path tools
+  - **Skills structure validation** (test/skills-structure.test.js): 34 new tests
+  - **Legacy cleanup**: Deleted `.claude/skills/parallel-ai/` (5 files) and `.claude/skills/sonarcloud/` (2 files)
+- **Impact**: 67 new PR5.5-specific tests, skills.sh compatible structure, users can download individual skills on demand without bloating npm package
+- **Files**: skills/ (7 new files), lib/plugin-catalog.js, lib/commands/recommend.js, test/skills-structure.test.js (new), test/plugin-catalog.test.js (+6 tests), test/plugin-recommend.test.js (new), package.json, .claude/commands/research.md
+- **Validation**: 974/1012 tests passing (2 pre-existing failures in packages/skills unrelated to PR5.5), all 18 CI checks passing, Greptile Quality Gate PASSED, SonarCloud Quality Gate PASSED (0 issues after fix), CodeQL false positive dismissed
+- **Security**: OWASP Top 10 reviewed (all N/A or PASS for static data + display-only changes), skills excluded from npm package by default, catalog frozen immutable data
+
+### PR6: Plugin Architecture & Smart Recommendations (2026-02-21)
+- **PR**: #41
+- **Beads**: forge-a7n (closed)
+- **Research**: [docs/research/plugin-architecture.md](../research/plugin-architecture.md)
+- **Description**: Read-only plugin catalog with 30 curated tools, tech stack detection across 9 categories, recommendation engine with 5 budget modes, and `forge recommend` CLI command
+- **Deliverables**:
+  - **Plugin Catalog** (lib/plugin-catalog.js):
+    - 30 tools across 7 workflow stages (research → merge)
+    - 4 pricing tiers: free, free-public, free-limited, paid
+    - 5 tool types: cli, skill, mcp, config, lsp
+    - 5 budget modes: free, open-source, startup, professional, custom
+    - Prerequisite registry (data-only, runtime deferred to PR7)
+    - Frozen immutable data, zero runtime I/O
+    - Every paid/free-limited tool has free alternatives
+    - CLI-first principle: MCPs only when no CLI equivalent exists
+    - 21 comprehensive tests
+  - **Tech Stack Detection** (lib/project-discovery.js, additive):
+    - `detectTechStack()` covering 9 categories: frameworks, languages, databases, auth, payments, CI/CD, testing, linting, LSPs
+    - 50+ technologies recognized across 12 internal helper functions
+    - Backward compatible: existing `detectFramework()`, `autoDetect()`, `detectLanguage()` unchanged
+    - 20 comprehensive tests (temp dir fixtures, backward compat)
+  - **Recommendation Engine** (lib/plugin-recommender.js):
+    - `recommend(techStack, budgetMode)` → `{ recommended, skipped }`
+    - `matchesDetection(conditions, techStack)` — OR logic for dep/file/framework conditions
+    - CLI-first enforcement, tier-based sorting (free first)
+    - Budget mode validation
+    - 26 comprehensive tests
+  - **CLI Command** (lib/commands/recommend.js, bin/forge.js):
+    - `forge recommend` with `--budget <mode>` flag
+    - Stage-grouped output with tier labels [F]/[FP]/[FL]/[P]
+    - Free alternatives shown inline for paid tools
+    - Default budget: startup
+    - 11 comprehensive tests
+- **Impact**: 78 new tests (930 total), read-only architecture with zero side effects, foundation for PR7 installation orchestrator
+- **Files**: lib/plugin-catalog.js (new), lib/plugin-recommender.js (new), lib/commands/recommend.js (new), lib/project-discovery.js (+149 lines), bin/forge.js (+22 lines), test/plugin-catalog.test.js, test/plugin-detection.test.js, test/plugin-recommender.test.js, test/commands/recommend.test.js
+- **Validation**: 930/930 tests passing, 0 ESLint warnings, all 19 CI checks passing, Greptile PASSED (0 comments), SonarCloud Quality Gate PASSED (0 open issues)
+- **Security**: OWASP Top 10 reviewed (all N/A or PASS for read-only data module), Object.freeze() on all catalog data, no user input flows to subprocess calls
+
+### PR5: Advanced Testing Expansion (2026-02-20)
+- **PR**: #40
+- **Beads**: forge-01p (closed)
+- **Research**: [docs/research/advanced-testing.md](../research/advanced-testing.md) (PR #36, merged 2026-02-20)
+- **Description**: Advanced testing infrastructure with Stryker mutation testing, performance benchmarks, OWASP A02/A07 security tests, and test quality dashboard
+- **Deliverables**:
+  - **Stryker Mutation Testing** (stryker.config.json):
+    - Command runner mode with `bun test` for Bun compatibility
+    - Scope: `lib/**/*.js` (excludes `bin/forge.js` CLI entry point)
+    - Thresholds: high 80, low 60, break 50
+    - Incremental mode for faster CI re-runs
+    - Weekly schedule (Sunday 3am UTC) + manual dispatch
+    - 10 comprehensive tests validating configuration
+  - **Performance Benchmarks** (scripts/benchmark.js):
+    - CLI startup benchmark (`node bin/forge.js --help`)
+    - `autoDetect()` and `detectFramework()` timing
+    - Safe subprocess handling with `execFileSync` (no shell injection)
+    - JSON output for CI integration
+    - 6 comprehensive tests
+  - **OWASP A02 Cryptographic Failure Tests** (test-env/edge-cases/crypto-security.test.js):
+    - .gitignore patterns for .env files (3 tests)
+    - No hardcoded secrets in lib/ and bin/ (2 tests)
+    - AGENTS.md template and MCP config clean (2 tests)
+    - No tracked .env files (1 test)
+    - 8 comprehensive tests
+  - **OWASP A07 Authentication Security Tests** (test-env/edge-cases/auth-security.test.js):
+    - Branch protection validates main/master
+    - No default credentials in templates
+    - Config files use process.env for tokens
+    - 6 comprehensive tests
+  - **Test Quality Dashboard** (scripts/test-dashboard.js):
+    - File-based test counting (avoids recursive `bun test`)
+    - Coverage threshold from c8 config
+    - Mutation score from Stryker report
+    - Skipped test detection
+    - CI job with artifact upload (needs test+coverage)
+    - 6 comprehensive tests
+  - **CI Workflow Enhancements** (.github/workflows/test.yml):
+    - `mutation` job: weekly + manual, Stryker run, 30-day artifact retention
+    - `dashboard` job: depends on test+coverage, generates dashboard, 7-day retention
+    - `schedule` trigger: cron `0 3 * * 0` (Sunday 3am UTC)
+    - 8 new CI validation tests
+- **Impact**: 44 new tests (851 total), mutation testing infrastructure, OWASP security validation, automated quality dashboard
+- **Files**: stryker.config.json, scripts/benchmark.js, scripts/test-dashboard.js, test/mutation-config.test.js, test/benchmarks.test.js, test/test-dashboard.test.js, test-env/edge-cases/crypto-security.test.js, test-env/edge-cases/auth-security.test.js, test/ci-workflow.test.js, .github/workflows/test.yml, package.json, .gitignore, .forge/hooks/check-tdd.js
+- **Validation**: 851/852 tests passing (1 pre-existing flaky), 0 ESLint warnings, all 22 CI checks passing, Greptile PASSED, SonarCloud Quality Gate PASSED (0 issues, 0 hotspots)
+- **Security**: OWASP A02+A07 automated tests, no hardcoded secrets, safe subprocess handling, branch protection validated
+
+### Pre-PR5 Code Quality Cleanup (2026-02-20)
+- **PR**: #34
+- **Beads**: forge-y8z (closed), forge-eb5 (closed)
+- **Description**: Resolved all pending code quality issues before starting PR5
+- **Deliverables**:
+  - **ESLint Strict Mode**:
+    - Resolved all 27 remaining `no-unused-vars` warnings across 11 test/validation files
+    - Enabled `--max-warnings 0` in lefthook.yml pre-push hook
+    - Zero warnings enforced going forward
+  - **SonarCloud Cognitive Complexity** (rework of closed PR #32):
+    - Extracted 15+ helper functions from `bin/forge.js` to reduce cognitive complexity
+    - Phase 7A: `installViaBunx`, `detectFromLockFile`, `detectFromCommand`, `validateCommonSecurity`, `getSkillsInstallArgs`, `installSkillsWithMethod`
+    - Phase 7B: `displayMcpStatus`, `displayEnvTokenResults`, `autoInstallLefthook`, `autoSetupToolsInQuickMode`, `configureDefaultExternalServices`
+    - Phase 7C: S6509 `Boolean()`, S3800 return consistency, S3516 error handling, S4144 duplicate function delegation
+  - **Cleanup**: Removed 15 redundant `.gitkeep` files, vestigial XML tags, scratch research docs
+  - **Tests**: 10 new structural tests in `test/cli/forge.test.js` verifying extracted helpers
+- **Impact**: Clean codebase for PR5, zero ESLint warnings, SonarCloud quality improvements
+- **Files**: bin/forge.js (870 lines changed), lefthook.yml, .claude/commands/sonarcloud.md, test/cli/forge.test.js (new), 11 test/validation files
+- **Validation**: 808/808 tests passing, 0 ESLint warnings, all 20 CI checks passing, Greptile PASSED, SonarCloud PASSED
+
+### PR4: CLI Command Automation (2026-02-19)
+- **PR**: #33
+- **Beads**: forge-01p (epic)
+- **Description**: Comprehensive CLI automation framework with 9-stage Forge workflow commands, parallel-ai integration, and beads/openspec toolchain support
+- **Validation**: 796+ tests passing, all CI checks green, Greptile PASSED, SonarCloud PASSED
+
+### PR3: Testing Infrastructure Foundation (2026-02-14)
+- **PR**: #30
+- **Beads**: forge-5uh
+- **Plan**: [.claude/plans/enumerated-watching-chipmunk.md](../../.claude/plans/enumerated-watching-chipmunk.md) (Phase 1 - PR3)
+- **Description**: Comprehensive testing infrastructure with code coverage integration, E2E testing framework, snapshot testing, and enhanced CI/CD workflows
+- **Deliverables**:
+  - **Code Coverage Integration** (c8):
+    - c8@10.1.3 with 80% thresholds (lines, branches, functions, statements)
+    - Coverage exclusions: test files, fixtures, coverage directory
+    - HTML, lcov, and text reporters for comprehensive reporting
+    - 9 comprehensive tests (dependencies, scripts, thresholds, badge, gitignore)
+  - **E2E Testing Framework** (test/e2e/):
+    - Scaffold utilities: createTempProject, cleanupTempProject
+    - Safety checks prevent accidental deletion of non-test directories
+    - Cross-platform temp directory handling (Windows, macOS, Linux)
+    - Test fixtures: empty-project, existing-project, large-project
+    - 8 E2E tests covering scaffold, fixtures, and snapshots
+  - **Snapshot Testing**:
+    - Node.js built-in snapshot testing (no external dependencies)
+    - Cross-platform compatibility (sorted arrays for consistent ordering)
+    - Snapshot validation for project structure
+    - Auto-generation and validation of snapshots
+  - **CI Workflow Enhancements** (.github/workflows/test.yml):
+    - Separate coverage job with artifact upload (7-day retention)
+    - Separate E2E job for isolated testing
+    - Parallel execution: test (6 platforms) + coverage + e2e
+    - 20 comprehensive tests validating workflow structure
+  - **Security Fix**:
+    - Fixed CodeQL Alert #90: Incomplete URL substring sanitization (test/coverage-config.test.js:98)
+    - Replaced insecure `readme.includes('shields.io')` with proper URL validation
+    - Validates hostname using URL API, trusts only known badge providers
+    - Prevents malicious URLs like `evil.com/shields.io/malware`
+- **Impact**: Foundation for comprehensive testing with 80%+ coverage thresholds, E2E testing infrastructure for workflow validation, parallel CI jobs for faster feedback
+- **Files**: package.json (c8 config), test/coverage-config.test.js, test/e2e/helpers/scaffold.js, test/e2e/helpers/cleanup.js, test/e2e/fixtures.test.js, test/e2e/snapshot.test.js, test/ci-workflow.test.js, .github/workflows/test.yml (coverage + e2e jobs), eslint.config.js (fixture ignores)
+- **Validation**: 695/695 tests passing (97%+ coverage), 0 ESLint errors, all 19 CI checks passing, Greptile PASSED, SonarCloud Quality Gate PASSED, CodeQL security alert resolved
+- **Security**: OWASP Top 10 validated, CodeQL Alert #90 fixed (proper URL validation), temp directory safety checks, no command injection risks
+
+### PR2: Branch Protection & Security Enhancements (2026-02-14)
+- **PR**: #29
+- **Plan**: [.claude/plans/enumerated-watching-chipmunk.md](../../.claude/plans/enumerated-watching-chipmunk.md) (Phase 1 - PR2)
+- **Description**: Comprehensive security enhancements including code ownership, commit message validation, vulnerability reporting process, commit signing guidance, and security badges
+- **Deliverables**:
+  - **CODEOWNERS File** (.github/CODEOWNERS):
+    - Team-based code ownership for critical directories
+    - 6 teams: core, workflow, docs, devops, testing, security
+    - Protected dirs: /bin/, /lib/, /.claude/, /docs/, .github/, security-sensitive files
+    - 8 comprehensive tests (file validation, directory protection, team syntax)
+  - **Commitlint Integration** (.commitlintrc.json, lefthook.yml):
+    - Enforce conventional commit message format (feat, fix, docs, etc.)
+    - Dependencies: @commitlint/cli@20.4.1, @commitlint/config-conventional@20.4.1
+    - Integrated with lefthook commit-msg hook
+    - 9 comprehensive tests (config, dependencies, hook integration)
+  - **SECURITY.md Policy**:
+    - Comprehensive vulnerability reporting process
+    - GitHub Security Advisories + email contact methods
+    - Response timeline: 48h initial, 5 days update
+    - Responsible disclosure process, security best practices
+    - 9 comprehensive tests (required sections, contact info, response timeline)
+  - **Branch Protection Guide Updates** (.github/BRANCH_PROTECTION_GUIDE.md):
+    - Added comprehensive commit signing section (228 lines)
+    - GPG signing setup (step-by-step)
+    - SSH signing setup (alternative, simpler)
+    - Troubleshooting guide (3 common issues)
+    - Team commit signing policy
+  - **Security Badges** (README.md):
+    - CodeQL security scanning badge
+    - Security Policy badge (links to SECURITY.md)
+  - **Security Fix**:
+    - Fixed markdown-it ReDoS vulnerability (GHSA-38c4-r59v-3vqw)
+    - Updated markdown-it from ^14.1.0 → ^14.1.1
+    - Security audit: No vulnerabilities found
+- **Impact**: Enhanced security with team-based access control, commit validation, vulnerability reporting, and commit signing guidance. Zero new vulnerabilities introduced.
+- **Files**: .github/CODEOWNERS, .commitlintrc.json, SECURITY.md, lefthook.yml (commit-msg hook), .github/BRANCH_PROTECTION_GUIDE.md (+228 lines), README.md (security badges), packages/skills/package.json (security fix), test/codeowners.test.js, test/commitlint.test.js, test/security-policy.test.js
+- **Validation**: 633/633 tests passing (26 new PR2 tests), 0 ESLint errors, 0 security vulnerabilities, Greptile PASSED (no issues), SonarCloud Quality Gate PASSED, all 18 CI checks passing
+- **Security**: OWASP Top 10 validated (A01-A10), markdown-it ReDoS fixed, commit signing prevents impersonation, CODEOWNERS adds access control, commitlint prevents malicious commit messages
+
+### PR1: Critical Fixes & Immediate Improvements (2026-02-13)
+- **PR**: #28
+- **Plan**: [.claude/plans/enumerated-watching-chipmunk.md](../../.claude/plans/enumerated-watching-chipmunk.md) (Phase 1)
+- **Description**: Quick wins to fix broken features and add immediate value - unified check script, Windows compatibility, package size monitoring, manual review guidance
+- **Deliverables**:
+  - **Unified Check Script** (scripts/check.sh):
+    - Orchestrates all validation: typecheck → lint → security → tests
+    - Single command: `bun run check`
+    - Cross-platform compatible (bash with fallback)
+    - 9 comprehensive tests covering orchestration, output, error handling
+  - **Lefthook Windows Compatibility** (scripts/branch-protection.js):
+    - Replaced bash script with Node.js for cross-platform support
+    - Works on Windows, macOS, Linux
+    - 11 tests covering branch logic, exit codes, platform execution
+  - **Package Size Monitoring** (.github/workflows/size-check.yml):
+    - Automated package size checks on PRs
+    - 10MB threshold with automated PR comments
+    - README badge integration
+    - 11 tests validating workflow configuration
+    - Fixed 3 Greptile issues: permissions, await, type coercion
+  - **Manual Review Guide** (docs/MANUAL_REVIEW_GUIDE.md):
+    - Comprehensive guidance for AI-assisted code review
+    - Best practices for Greptile, CodeRabbit, SonarCloud
+    - OWASP Top 10 security checklist
+    - Integration with /review stage
+  - **Security Fix**:
+    - Updated inquirer to v13.2.2 (fixed tmp vulnerability)
+- **Impact**: Immediate workflow improvements, cross-platform git hooks, automated size monitoring, enhanced review quality
+- **Files**: scripts/check.sh, scripts/branch-protection.js, .github/workflows/size-check.yml, docs/MANUAL_REVIEW_GUIDE.md, lefthook.yml, package.json, packages/skills/package.json, .claude/commands/check.md, test/check-script.test.js, test/branch-protection.test.js, test/workflows/size-check.test.js
+- **Validation**: 607/607 tests passing, 0 ESLint errors, Greptile 5/5 (all threads resolved), SonarCloud ✅, all 17 CI checks passing
+- **Security**: tmp vulnerability fixed (inquirer upgrade), OWASP Top 10 validated, shell injection prevented (Node.js scripts), no new attack surfaces
+
+### PR0: Architecture Simplification & Multi-Agent Support (2026-02-12)
+- **PR**: #26
+- **Beads**: forge-wp2
+- **Plan**: [.claude/plans/enumerated-watching-chipmunk.md](../../.claude/plans/enumerated-watching-chipmunk.md)
+- **Description**: Simplified Forge architecture from 11 agents to 5 Tier 1 + 3 Tier 2 agents with universal AGENTS.md configuration
+- **Deliverables**:
+  - **New Modules** (2,346 lines):
+    - lib/agents-config.js (2,228 lines): 6 generators + 3 doc generators
+    - lib/setup.js (118 lines): Resumable setup state management
+  - **Test Suite** (104 new tests):
+    - 9 new test files covering agent detection, config generation, E2E workflows
+    - All 576 tests passing (100% pass rate)
+  - **Multi-Agent Support**:
+    - Tier 1: Claude Code, GitHub Copilot, Kilo Code, Cursor, Aider
+    - Tier 2: OpenCode, Goose, Antigravity
+    - Universal AGENTS.md + optional agent-specific configs
+  - **Documentation**:
+    - Updated CLAUDE.md with Multi-Agent Support section
+    - Smart setup with auto-detection (30-second setup)
+    - Resumable setup state (.forge/setup-state.json)
+- **Impact**: Foundation for all subsequent PRs, zero coordination complexity, 67% reduction in multi-agent coordination issues
+- **Files**: lib/agents-config.js, lib/setup.js, lib/project-discovery.js, CLAUDE.md, test/*.test.js, test/e2e/setup-workflow.test.js
+- **Validation**: 576/576 tests passing, 0 ESLint errors, OWASP Top 10 verified, Greptile ✅, SonarCloud ✅
+- **Security**: No new dependencies, file-based state management, overwrite protection, OWASP A03/A04/A05/A06/A08 validated
+
+### YAML Validation Workflow (2026-02-10)
+- **PR**: #23
+- **Description**: Added automated YAML syntax validation to prevent configuration errors in CI/CD workflows
+- **Deliverables**:
+  - New GitHub Actions workflow: `.github/workflows/yaml-lint.yml`
+  - Local validation script: `bun run validate:yaml`
+  - Committed dev dependency: js-yaml@^4.1.1
+  - Security hardening: Fixed shell injection, proper quoting, idempotent design
+  - Comprehensive validation: All `.yml` and `.yaml` files across entire repository
+- **Impact**: Prevents YAML syntax errors from reaching production, automated CI/CD validation
+- **Files**: .github/workflows/yaml-lint.yml, package.json, bun.lock
+- **Validation**: 471/472 tests passing, 0 ESLint errors, 0 SonarCloud issues, Greptile Quality Gate passed (≥4/5)
+- **Security**: OWASP Top 10 verified, all injection vulnerabilities fixed (4 rounds of Greptile review)
+
+### Package Manager Documentation Consistency (2026-02-09)
+- **PR**: #21
+- **Description**: Standardized all documentation to reference Bun as primary package manager with npm as fallback
+- **Deliverables**:
+  - Updated 14 documentation files: commands, rules, workflows, templates, README
+  - Updated lefthook.yml: pre-push hook now uses `bunx eslint .`
+  - Command replacements: 90+ instances (npm → bun, npx → bunx)
+  - Maintained backwards compatibility: npm shown as fallback option
+- **Impact**: 100% documentation consistency, improved user experience, aligned with project design
+- **Files**: .claude/commands/*, .claude/rules/workflow.md, .github/pull_request_template.md, CLAUDE.md, README.md, docs/*.md, lefthook.yml, openspec/AGENTS.md
+- **Validation**: 472/472 tests passing, 0 errors (ESLint), OWASP Top 10 verified, all 16 CI/CD checks passed
+
+### Comprehensive Test Environment (2026-02-05)
+- **PR**: #8
+- **Beads**: forge-hql (EPIC)
+- **Research**: [docs/research/test-environment.md](../research/test-environment.md)
+- **OpenSpec**: openspec/changes/test-environment/ (to be archived)
+- **Description**: Production-grade test infrastructure with 189 tests across edge cases, integration scenarios, and validation helpers
+- **Deliverables**:
+  - 8 edge case test files (120 tests): prerequisites, permissions, git states, network, JSON, file limits, security, env preservation
+  - 3 rollback test files (69 tests): edge cases, user sections, validation
+  - 4 validation helpers (52 tests): git-state-checker, env-validator, agent-validator, file-checker
+  - 15 test fixtures: covering fresh install, upgrades, conflicts, permissions, git states, frameworks, security
+  - Unified test infrastructure: Migrated all tests to test-env/, deleted old test/ directory
+  - Bug fixes: Critical path validation bug (bin/forge.js:116), git submodule cleanup
+- **Impact**: ~95% test coverage, automated CI/CD testing (18 jobs), comprehensive edge case validation
+- **Files**: test-env/edge-cases/*, test-env/validation/*, test-env/fixtures/*, test-env/README.md, lib/plugin-manager.js
+
+### Meta-Development Documentation (2026-02-03)
+- **PR**: #7
+- **Beads**: forge-66q
+- **Description**: Added contributor documentation enabling Forge workflow for Forge development (dogfooding)
+- **Files**: DEVELOPMENT.md, .github/CONTRIBUTING.md, .clinerules, .npmignore
+
+## Upcoming
+<!-- Next priorities -->
+
+### PR5.5: Skills Restructure for skills.sh
+- **Deliverables**: Restructure parallel-ai into 4 focused skills, publish to skills.sh, add citation-standards rule
+- **Status**: ✅ Merged as PR #43
+
+### PR7: Installation Orchestrator + Skill Extraction
+- **Deliverables**: `forge install <tool>` command, prerequisite runtime verification, skill extraction from npm `files`, cross-platform installer
+- **Status**: Blocked on PR5.5 (skills.sh publishing)
+- **Research**: Risk analysis R1-R6 in [docs/research/plugin-architecture.md](../research/plugin-architecture.md)
+
+### PR8: Catalog Expansion
+- **Deliverables**: Expand catalog from 30 to 90+ tools, language-specific LSPs, community feedback integration
+- **Status**: After PR7

package/docs/plans/2026-02-27-forge-test-suite-v2-decisions.md

@@ -0,0 +1,21 @@
+# Decisions Log: Forge Test Suite v2
+
+**Feature**: forge-test-suite-v2
+**Beads**: forge-5vf
+**Started**: 2026-02-27
+
+---
+
+<!-- Decisions appended below as they arise during /dev -->
+
+## Decision 1
+**Date**: 2026-02-27
+**Task**: Task 1 — Audit and delete stale lib exports
+**Gap**: `lib/commands/research.js` has a live non-test reference in `bin/forge-cmd.js` line 14. The `forge research` CLI command is still registered in VALID_COMMANDS, COMMAND_DESCRIPTIONS, REQUIRED_ARGS, dispatch handler, and help text. Deleting lib only requires also removing the CLI registration — user-visible behavior change not specified in Task 1.
+**Score**: 7/14 (SPEC-REVIEWER range) — also matches explicit "SHOULD pause and ask" example in ambiguity policy
+**Route**: BLOCKED — PENDING-DEVELOPER-INPUT
+**Choice made**: Option A — full deletion. User confirmed lib/commands/research.js is a stub (conductResearch() returns empty arrays, forge research CLI produces useless empty documents).
+**Options**:
+  A. Full deletion: remove lib/commands/research.js AND all forge research CLI registration from bin/forge-cmd.js (removes forge research as a user command) ← CHOSEN
+  B. Partial: keep lib/commands/research.js and the CLI command — skip deletion, only remove OpenSpec functions from lib/commands/plan.js
+**Status**: RESOLVED