vibe-forge 0.4.0 → 0.8.2

package/tasks/completed/SEC-007-spawn-escaping.md

@@ -1,67 +0,0 @@
----
-id: SEC-007
-title: "Escape variables in Windows Terminal spawn command"
-type: security
-priority: low
-assigned_to: aegis
-created_at: 2026-01-16T00:00:00Z
-created_by: scribe-docs-migration
----
-
-## Summary
-Variables passed to Windows Terminal command are not properly escaped for nested shell invocation.
-
-## Current State
-From docs/TODO.md (L-1 - Low Priority):
-> **Windows Terminal command escaping**
-> File: `bin/forge-spawn.sh` lines 55-57
-> Issue: `$display_name` and `$FORGE_ROOT` not escaped for nested shell invocation
-> Fix: Use `printf %q` for proper escaping
-
-Current code:
-```bash
-wt.exe "${wt_args[@]}" "$bash_path" -c "cd \"$win_forge_root\" && ./bin/forge.sh start \"$agent\""
-```
-
-The `$win_forge_root` and other variables could contain characters that break the nested shell command.
-
-## Affected Files
-- `bin/forge-spawn.sh` lines 55-57 (and nearby)
-
-## Proposed Fix
-Use `printf %q` to properly escape variables before embedding in the command string:
-```bash
-escaped_path=$(printf %q "$win_forge_root")
-escaped_agent=$(printf %q "$agent")
-wt.exe "${wt_args[@]}" "$bash_path" -c "cd $escaped_path && ./bin/forge.sh start $escaped_agent"
-```
-
-## Risk Assessment
-Low risk because:
-- $agent is already validated through resolve_agent whitelist
-- $FORGE_ROOT is set from script directory, not user input
-
-Still worth fixing for defense in depth.
-
-## Acceptance Criteria
-- [x] Variables properly escaped with printf %q
-- [x] Works with paths containing spaces
-- [x] Works with paths containing special characters
-- [ ] Test on Windows with various path types (manual testing required)
-
-## Resolution
-
-**Status: Fixed**
-
-Updated `bin/forge-spawn.sh` lines 76-87 to use `printf %q` for proper escaping:
-
-```bash
-# SECURITY: Use printf %q to properly escape paths for nested shell invocation
-local escaped_path escaped_agent
-escaped_path=$(printf %q "$win_forge_root")
-escaped_agent=$(printf %q "$agent")
-
-wt.exe "${wt_args[@]}" "$bash_path" -c "cd $escaped_path && ./bin/forge.sh start $escaped_agent"
-```
-
-This ensures paths with spaces, special characters, or shell metacharacters are properly escaped for the nested shell invocation.

package/tasks/pending/ARCH-004-git-bash-detection-duplication.md

@@ -1,72 +0,0 @@
----
-id: ARCH-004
-title: "Consolidate Git Bash detection logic"
-type: architecture
-priority: low
-assigned_to: architect
-created_at: 2026-01-15T17:00:00Z
-created_by: architect-review
----
-
-## Summary
-Git Bash path detection is implemented in four different places with slightly different logic and paths checked.
-
-## Current State
-Git Bash detection exists in:
-
-1. **bin/cli.js** - getBashPath() function (lines 105-136)
-   - Checks 3 hardcoded paths
-   - Uses `where git` fallback
-   - Returns null if not found
-
-2. **bin/forge.cmd** - Batch script (lines 42-74)
-   - Checks 4 hardcoded paths (different from cli.js)
-   - Uses `where git` fallback
-   - Shows error if not found
-
-3. **bin/forge-setup.sh** - find_git_bash() function (lines 59-134)
-   - Checks 6+ paths including $LOCALAPPDATA
-   - Uses `where git` fallback
-   - Offers to install via winget
-
-4. **bin/lib/terminal.js** - findGitBash() function (lines 195-223)
-   - Checks 3 hardcoded paths
-   - Uses `where git` fallback
-   - Returns null if not found
-
-Problems:
-- Different paths checked in each implementation
-- Logic duplicated 4 times
-- Different fallback behaviors
-- D: drive paths only in some implementations
-- $LOCALAPPDATA only in some implementations
-
-## Proposed State
-Single shared implementation:
-
-1. Create `bin/lib/git-bash.js` with comprehensive path detection
-2. Export for use in cli.js and terminal.js
-3. Provide bash-callable interface for shell scripts
-4. Or: store detected path in config, read from all scripts
-
-## Affected Files
-- G:\dev\vibe-forge\bin\cli.js
-- G:\dev\vibe-forge\bin\forge.cmd
-- G:\dev\vibe-forge\bin\forge-setup.sh
-- G:\dev\vibe-forge\bin\lib\terminal.js
-
-## Migration/Remediation Steps
-1. Create unified git-bash.js module with all known paths
-2. Export as CLI: `node git-bash.js` -> outputs path
-3. Update cli.js to use shared module
-4. Update terminal.js to use shared module
-5. Update forge-setup.sh to call Node.js module
-6. Update forge.cmd to read from config (set during init)
-7. Ensure all 6+ paths are checked consistently
-
-## Acceptance Criteria
-- [ ] Single source of truth for Git Bash detection
-- [ ] All known paths (C:, D:, LOCALAPPDATA) checked consistently
-- [ ] Detection works from bash and Node.js
-- [ ] All tests passing
-- [ ] Windows functionality unchanged

package/tasks/pending/ARCH-005-missing-src-directory.md

@@ -1,95 +0,0 @@
----
-id: ARCH-005
-title: "Establish proper source code organization with src/ directory"
-type: architecture
-priority: low
-assigned_to: architect
-created_at: 2026-01-15T17:00:00Z
-created_by: architect-review
----
-
-## Summary
-The codebase lacks a conventional src/ directory structure. All source files are in bin/ or bin/lib/, mixing executable entry points with library code.
-
-## Current State
-Current structure:
-```
-bin/
-  cli.js           <- Entry point
-  forge.sh         <- Entry point
-  forge.cmd        <- Entry point
-  forge-setup.sh   <- Could be library
-  forge-spawn.sh   <- Could be library
-  forge-daemon.sh  <- Could be library
-  lib/
-    colors.sh      <- Library
-    constants.sh   <- Library
-    config.sh      <- Library
-    agents.sh      <- Library
-    database.sh    <- Library
-    terminal.js    <- Library
-```
-
-Problems:
-- Entry points mixed with implementation files
-- No clear distinction between bin/ (executables) and src/ (source)
-- .gitignore references src/ as a tool internal (line 232) but no src/ exists
-- Node convention is bin/ for CLI entry points, src/ for implementation
-
-## Proposed State
-Reorganize to:
-```
-bin/
-  cli.js           <- Entry point (thin wrapper)
-  forge            <- Symlink or wrapper to src/cli/forge.sh
-src/
-  cli/
-    forge.sh       <- Main CLI implementation
-    setup.sh       <- Setup logic
-    spawn.sh       <- Spawn logic
-    daemon.sh      <- Daemon logic
-  lib/
-    colors.sh      <- Shared utilities
-    constants.sh   <- Constants
-    config.sh      <- Config utilities
-    agents.sh      <- Agent utilities
-    database.sh    <- DB utilities
-    terminal.js    <- Terminal utilities
-    git-bash.js    <- Git bash detection
-```
-
-Or for Node.js migration:
-```
-bin/
-  vibe-forge.js    <- CLI entry point
-src/
-  cli/
-    index.js       <- Command routing
-    init.js        <- Init command
-    start.js       <- Start command
-    spawn.js       <- Spawn command
-  lib/
-    config.js
-    agents.js
-    terminal.js
-```
-
-## Affected Files
-- All files in G:\dev\vibe-forge\bin\
-- G:\dev\vibe-forge\package.json (files array)
-
-## Migration/Remediation Steps
-1. Create src/ directory
-2. Move bin/lib/* to src/lib/
-3. Update imports/sources in bin/*.sh scripts
-4. Update package.json files array if needed
-5. Ensure tests still work
-6. Update documentation
-
-## Acceptance Criteria
-- [ ] Clear separation between entry points and implementation
-- [ ] src/ directory exists with organized code
-- [ ] bin/ contains only entry point wrappers
-- [ ] All imports updated
-- [ ] Tests passing
-- [ ] Documentation updated

package/tasks/pending/ARCH-006-task-template-location.md

@@ -1,64 +0,0 @@
----
-id: ARCH-006
-title: "Move task-template.md to templates directory"
-type: architecture
-priority: low
-assigned_to: architect
-created_at: 2026-01-15T17:00:00Z
-created_by: architect-review
----
-
-## Summary
-Task template is stored in config/ but is not a configuration file - it's a template. Should be in a dedicated templates directory.
-
-## Current State
-```
-config/
-  agents.json         <- Configuration
-  agent-manifest.yaml <- Configuration (or docs)
-  task-types.yaml     <- Configuration
-  task-template.md    <- Template (not config!)
-```
-
-The task-template.md is referenced from:
-- .claude/commands/forge.md (line 124): `@_vibe-forge/config/task-template.md`
-
-## Proposed State
-Create templates/ directory:
-```
-config/
-  agents.json
-  task-types.yaml
-templates/
-  task-template.md
-  project-context-template.md  <- Move from context/
-```
-
-Or alternatively, rename to config/templates/:
-```
-config/
-  agents.json
-  task-types.yaml
-  templates/
-    task.md
-    project-context.md
-```
-
-## Affected Files
-- G:\dev\vibe-forge\config\task-template.md
-- G:\dev\vibe-forge\context\project-context-template.md
-- G:\dev\vibe-forge\.claude\commands\forge.md
-
-## Migration/Remediation Steps
-1. Create templates/ directory
-2. Move config/task-template.md to templates/
-3. Move context/project-context-template.md to templates/
-4. Update reference in .claude/commands/forge.md
-5. Update any other references (forge-setup.sh uses context template)
-6. Update package.json files array if needed
-
-## Acceptance Criteria
-- [ ] Templates in dedicated templates/ directory
-- [ ] All references updated
-- [ ] Functionality unchanged
-- [ ] Package includes templates directory

package/tasks/pending/ARCH-007-daemon-monolith.md

@@ -1,91 +0,0 @@
----
-id: ARCH-007
-title: "Split forge-daemon.sh into focused modules"
-type: architecture
-priority: medium
-assigned_to: architect
-created_at: 2026-01-15T17:00:00Z
-created_by: architect-review
----
-
-## Summary
-forge-daemon.sh is a 776-line monolith containing multiple unrelated responsibilities. Should be split into focused modules for better maintainability.
-
-## Current State
-forge-daemon.sh contains:
-1. **Utility functions** (lines 56-111)
-   - Log rotation
-   - Notification trimming
-   - Safe file move
-
-2. **Notification system** (lines 117-263)
-   - notify()
-   - send_system_notification() - platform-specific
-   - check_new_pending_tasks()
-   - check_attention_needed()
-
-3. **Status synchronization** (lines 265-345)
-   - sync_agent_status_to_db()
-   - build_worker_status()
-
-4. **State management** (lines 351-463)
-   - update_state()
-   - build_attention_details()
-   - route_completed_to_review()
-   - route_approved_to_merged()
-   - determine_daemon_state()
-   - get_poll_interval()
-
-5. **Daemon loop** (lines 473-533)
-   - daemon_loop()
-
-6. **Commands** (lines 539-742)
-   - cmd_start()
-   - cmd_stop()
-   - cmd_status()
-   - cmd_notifications()
-   - cmd_clear_notifications()
-
-## Proposed State
-Split into focused modules:
-```
-bin/lib/
-  daemon/
-    notifications.sh  <- Notification logic
-    sync.sh          <- Agent status sync
-    state.sh         <- State file management
-    routing.sh       <- Task routing logic
-bin/
-  forge-daemon.sh    <- Thin wrapper using modules
-```
-
-Or for Node.js migration:
-```
-src/daemon/
-  index.js           <- Main daemon loop
-  notifications.js   <- Notification system
-  sync.js            <- Agent status sync
-  state.js           <- State management
-  routing.js         <- Task routing
-```
-
-## Affected Files
-- G:\dev\vibe-forge\bin\forge-daemon.sh
-- G:\dev\vibe-forge\bin\lib\database.sh (related)
-
-## Migration/Remediation Steps
-1. Create bin/lib/daemon/ directory
-2. Extract notification functions to notifications.sh
-3. Extract sync functions to sync.sh
-4. Extract state functions to state.sh
-5. Extract routing functions to routing.sh
-6. Update forge-daemon.sh to source modules
-7. Ensure all tests pass
-8. Update documentation
-
-## Acceptance Criteria
-- [ ] forge-daemon.sh under 200 lines
-- [ ] Each module has single responsibility
-- [ ] No circular dependencies between modules
-- [ ] Tests passing
-- [ ] Daemon functionality unchanged

package/tasks/pending/ARCH-008-forge-master-vs-hub.md

@@ -1,81 +0,0 @@
----
-id: ARCH-008
-title: "Resolve forge-master vs hub naming inconsistency"
-type: architecture
-priority: low
-assigned_to: architect
-created_at: 2026-01-15T17:00:00Z
-created_by: architect-review
----
-
-## Summary
-The planning/coordination agent is referred to by different names in different places, causing confusion and potential issues.
-
-## Current State
-Naming inconsistencies:
-
-1. **agents/forge-master/** - Directory uses "forge-master"
-   - Contains personality.md, capabilities.md, context-template.md
-
-2. **agents/planning-hub/** - Different directory uses "planning-hub"
-   - Contains personality.md
-
-3. **config/agents.json** - Uses "hub"
-   ```json
-   "hub": {
-     "name": "Planning Hub",
-     "personality_file": "agents/planning-hub/personality.md"
-   }
-   ```
-
-4. **config/agent-manifest.yaml** - Uses "forge-master"
-   ```yaml
-   core_agents:
-     forge-master:
-       name: "Forge Master"
-   ```
-
-5. **bin/lib/constants.sh** - Uses "hub" with "master" alias
-   ```bash
-   VALID_AGENTS=(..., "hub")
-   AGENT_ALIASES=([...], ["master"]="hub", ["forge-master"]="hub")
-   ```
-
-6. **Documentation** - Mixed usage
-
-Problems:
-- Two separate personality files that may differ
-- Confusion about canonical name
-- Extra data in forge-master/ (capabilities.md, context-template.md) not in planning-hub/
-
-## Proposed State
-Single consistent name:
-
-1. Pick canonical name: "hub" (shorter, already used in code)
-2. Pick personality directory: agents/hub/ or agents/planning-hub/
-3. Consolidate personality content
-4. Keep aliases for discoverability
-
-## Affected Files
-- G:\dev\vibe-forge\agents\forge-master\
-- G:\dev\vibe-forge\agents\planning-hub\
-- G:\dev\vibe-forge\config\agents.json
-- G:\dev\vibe-forge\config\agent-manifest.yaml
-- G:\dev\vibe-forge\bin\lib\constants.sh
-- G:\dev\vibe-forge\.claude\commands\forge.md
-
-## Migration/Remediation Steps
-1. Decide on canonical directory (planning-hub/ or hub/)
-2. Merge content from forge-master/ into canonical directory
-3. Delete or deprecate non-canonical directory
-4. Update agents.json personality_file path
-5. Update constants.sh fallback
-6. Update agent-manifest.yaml (or delete per ARCH-001)
-7. Search for all references and update
-
-## Acceptance Criteria
-- [ ] Single directory for hub/planning agent
-- [ ] Consistent naming across all config files
-- [ ] All content consolidated (personality, capabilities, context-template)
-- [ ] Aliases still work (master, forge-master, planning, hub)
-- [ ] Tests passing

package/tasks/pending/ARCH-010-missing-index-files.md

@@ -1,84 +0,0 @@
----
-id: ARCH-010
-title: "Add index files for cleaner module imports"
-type: architecture
-priority: low
-assigned_to: architect
-created_at: 2026-01-15T17:00:00Z
-created_by: architect-review
----
-
-## Summary
-The bin/lib/ directory lacks index files, requiring explicit file paths for imports. Node convention uses index.js for cleaner module exports.
-
-## Current State
-```
-bin/lib/
-  colors.sh
-  constants.sh
-  config.sh
-  agents.sh
-  database.sh
-  terminal.js
-```
-
-Each bash script sources files explicitly:
-```bash
-source "$SCRIPT_DIR/lib/colors.sh"
-source "$SCRIPT_DIR/lib/constants.sh"
-source "$SCRIPT_DIR/lib/config.sh"
-source "$SCRIPT_DIR/lib/agents.sh"
-```
-
-Problems:
-- No single entry point for bash libraries
-- If migrating to Node.js, no index.js for module export
-- Repetitive sourcing in every script
-
-## Proposed State
-For bash:
-```bash
-# bin/lib/index.sh
-#!/usr/bin/env bash
-LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$LIB_DIR/colors.sh"
-source "$LIB_DIR/constants.sh"
-source "$LIB_DIR/config.sh"
-source "$LIB_DIR/agents.sh"
-# database.sh loaded only when needed
-```
-
-Usage:
-```bash
-source "$SCRIPT_DIR/lib/index.sh"
-```
-
-For Node.js (if migrating):
-```javascript
-// bin/lib/index.js
-module.exports = {
-  terminal: require('./terminal'),
-  config: require('./config'),
-  agents: require('./agents'),
-};
-```
-
-## Affected Files
-- G:\dev\vibe-forge\bin\lib\ (new index.sh)
-- G:\dev\vibe-forge\bin\forge.sh
-- G:\dev\vibe-forge\bin\forge-setup.sh
-- G:\dev\vibe-forge\bin\forge-spawn.sh
-- G:\dev\vibe-forge\bin\forge-daemon.sh
-
-## Migration/Remediation Steps
-1. Create bin/lib/index.sh with all common sources
-2. Consider lazy loading for database.sh (only for daemon)
-3. Update all scripts to use single source
-4. If migrating to Node.js, create index.js
-5. Test all scripts still work
-
-## Acceptance Criteria
-- [ ] Single source command for common libraries
-- [ ] Reduced boilerplate in scripts
-- [ ] Functionality unchanged
-- [ ] Tests passing

package/tasks/pending/CLEAN-002.md

@@ -1,29 +0,0 @@
----
-id: CLEAN-002
-title: "Inconsistent task path references between shell and JS implementations"
-type: code-quality
-priority: medium
-assigned_to: furnace
-created_at: 2026-01-15T17:00:00Z
-created_by: sentinel-review
----
-
-## Summary
-The worker-loop.sh and worker-loop.js have inconsistent task directory paths:
-- Shell version uses `$FORGE_ROOT/tasks/pending/` (relative to FORGE_ROOT)
-- JS version uses `path.join(forgeRoot, '_vibe-forge', 'tasks')` (adds _vibe-forge prefix)
-
-This inconsistency could cause issues if both were used, and indicates the implementations have diverged.
-
-## Affected Files/Lines
-- `.claude/hooks/worker-loop.sh:65-66` - uses `$TASKS_DIR="$FORGE_ROOT/tasks"`
-- `.claude/hooks/worker-loop.js:116` - uses `path.join(forgeRoot, '_vibe-forge', 'tasks')`
-
-## Remediation
-1. Determine the correct path structure based on project layout
-2. Ensure the active JS implementation uses the correct path
-3. Document the expected directory structure
-
-## Acceptance Criteria
-- [ ] Consistent task directory path used across all implementations
-- [ ] Path works correctly in both standalone and embedded (_vibe-forge subdir) modes

package/tasks/pending/CLEAN-009.md

@@ -1,31 +0,0 @@
----
-id: CLEAN-009
-title: "Inconsistent agent naming between agent-manifest.yaml and constants.sh"
-type: code-quality
-priority: low
-assigned_to: furnace
-created_at: 2026-01-15T17:00:00Z
-created_by: sentinel-review
----
-
-## Summary
-The agent-manifest.yaml and constants.sh have inconsistent agent definitions:
-- agent-manifest.yaml defines `forge-master` as an agent
-- constants.sh defines `hub` as the canonical name with aliases like "planning", "master", "forge-master"
-- agent-manifest.yaml references personalities at `/agents/forge-master/` but constants.sh expects `agents/planning-hub/`
-
-## Affected Files/Lines
-- `config/agent-manifest.yaml:8-19` - defines forge-master with personality at `/agents/forge-master/personality.md`
-- `bin/lib/constants.sh:114-118` - defines hub with personality at `agents/planning-hub/personality.md`
-- `config/agent-manifest.yaml:123-160` - defines planning_agents (sage, oracle, quartermaster) not in constants.sh
-
-## Remediation
-1. Decide on single source of truth for agent definitions
-2. Either update constants.sh to match agent-manifest.yaml or vice versa
-3. Consider using agents.json as the canonical source and generating constants.sh fallbacks from it
-4. Ensure personality file paths are consistent
-
-## Acceptance Criteria
-- [ ] Single source of truth for agent definitions
-- [ ] Consistent naming between config files and code
-- [ ] All referenced personality files exist at specified paths

package/tasks/pending/CLEAN-010.md

@@ -1,30 +0,0 @@
----
-id: CLEAN-010
-title: "Unused planning_agents in agent-manifest.yaml"
-type: code-quality
-priority: low
-assigned_to: furnace
-created_at: 2026-01-15T17:00:00Z
-created_by: sentinel-review
----
-
-## Summary
-The agent-manifest.yaml defines several planning_agents (sage, oracle, quartermaster) that don't appear to be implemented or used anywhere in the codebase:
-- No corresponding entries in constants.sh
-- No personality files in agents/ directory for these agents
-- Not referenced in forge.md or other command files
-
-These may be planned features or dead configuration.
-
-## Affected Files/Lines
-- `config/agent-manifest.yaml:124-162` - sage, oracle, quartermaster definitions
-
-## Remediation
-1. If these are planned features, add a comment indicating they are not yet implemented
-2. If they are dead configuration, remove them to reduce confusion
-3. If they should be working, create the missing personality files and update constants.sh
-
-## Acceptance Criteria
-- [ ] Planning agents are either implemented or clearly marked as TODO
-- [ ] No orphaned configuration without corresponding implementation
-- [ ] Documentation updated to reflect actual vs. planned agents

package/tasks/pending/CLEAN-011.md

@@ -1,30 +0,0 @@
----
-id: CLEAN-011
-title: "Duplicate color definitions between cli.js and colors.sh"
-type: code-quality
-priority: low
-assigned_to: furnace
-created_at: 2026-01-15T17:00:00Z
-created_by: sentinel-review
----
-
-## Summary
-Color codes are defined in two places:
-- `bin/lib/colors.sh` - Bash color definitions
-- `bin/cli.js:26-33` - JavaScript color definitions
-
-The cli.js has a comment explaining why it's self-contained (runs via npx before rest is installed), but the color values themselves could potentially drift.
-
-## Affected Files/Lines
-- `bin/lib/colors.sh:9-22` - Bash color definitions (RED, GREEN, YELLOW, BLUE, CYAN, NC)
-- `bin/cli.js:26-33` - JavaScript color definitions (reset, red, green, yellow, blue, cyan)
-
-## Remediation
-The duplication is intentional per the comment in cli.js. No code changes needed, but:
-1. Add a comment in colors.sh noting the JavaScript equivalent exists
-2. If colors are updated in one place, update the other
-3. Consider adding a test to verify they match
-
-## Acceptance Criteria
-- [ ] Cross-reference comment added to colors.sh
-- [ ] Document the intentional duplication in code comments