@sugar-crash-studios/vibe-forge 0.4.0

package/tasks/review/bmad-review-ember.md

@@ -0,0 +1,307 @@
+# BMAD vs Vibe Forge: DevOps & Infrastructure Review
+
+**Reviewer:** Ember (DevOps Specialist)
+**Date:** 2026-03-31
+**Task:** review-bmad-ember
+**BMAD version reviewed:** 6.2.2
+
+---
+
+## Executive Summary
+
+BMAD-METHOD and Vibe Forge take fundamentally different architectural approaches. BMAD is a **static content package** - a CLI tool that installs Markdown files into an IDE. It has no runtime daemons, no containers, and no server infrastructure to operate. Vibe Forge is an **active orchestration system** with a running daemon, SQLite persistence, agent status tracking, and real task routing. This means most of Vibe Forge's infrastructure concerns have no BMAD equivalent to compare against - Vibe Forge is simply doing more.
+
+That said, BMAD's CI/CD pipeline and release automation are meaningfully more mature and have specific patterns Vibe Forge should adopt.
+
+---
+
+## 1. CI/CD Pipeline Analysis
+
+### Vibe Forge Current State
+
+Three workflows:
+- `ci.yml` - PR checks, lint, multi-OS install test, shellcheck, unit tests
+- `publish.yml` - npm publish on release (with semver validation + provenance)
+- `docs.yml` - VitePress deploy to GitHub Pages
+
+**Strengths:**
+- Multi-OS matrix (ubuntu, macos, windows) for install testing - critical for a cross-platform CLI
+- ShellCheck integration (pinned to `ludeeus/action-shellcheck@2.0.0`)
+- npm publish uses `--provenance` (OIDC trusted publishing)
+- Semver validation on manual version input
+- Post-publish verification step (`npm view vibe-forge version` after 30s)
+- Branch naming convention enforcement in PRs (warning, non-blocking)
+- Direct-to-main PR block enforcement
+
+**Gaps vs BMAD:**
+
+| Feature | Vibe Forge | BMAD |
+|---------|-----------|------|
+| Parallel quality jobs | Sequential in single job | 5 parallel jobs (prettier, eslint, markdownlint, docs, validate) |
+| Markdown linting in CI | None | `markdownlint-cli2` runs on every PR |
+| Formatting enforcement | None | `prettier --check` blocks PRs |
+| Docs build validation | Only on push to main | Runs on every PR |
+| Pre-commit hooks | None | Husky: lint-staged + tests + docs validation |
+| Auto-prerelease channel | None | `@next` tag auto-published on every main push |
+| Two-track release | Manual only | Auto-prerelease (`@next`) + manual stable (`@latest`) |
+| External validation | None | `validate:refs` and `validate:skills` catch broken internal links |
+| Discord notifications | None | Release + PR + issue notifications to community channel |
+| Community bot (CodeRabbit) | None | `coderabbitai review` auto-triggered on PR ready-for-review |
+
+**Key Gap: No `@next` channel.** Vibe Forge has no auto-prerelease. Every publish is manual and goes straight to `@latest`. BMAD's two-track system (auto `@next` on main, manual stable promotion) is the safer pattern - it lets users test bleeding-edge without touching the stable channel.
+
+**Key Gap: No pre-commit hooks.** BMAD uses Husky to run format/lint/tests locally before commit. Vibe Forge relies entirely on CI for feedback. This slows down the feedback loop significantly.
+
+**Key Gap: No markdown linting.** The entire Vibe Forge framework is Markdown-driven (agent personalities, task files, docs). No lint runs on these. Agent personality files could have broken formatting that passes CI silently.
+
+---
+
+## 2. Daemon Architecture Deep Dive
+
+### `forge-daemon.sh` Assessment
+
+This is Vibe Forge's most sophisticated infrastructure piece. BMAD has no equivalent.
+
+**What it does well:**
+
+- **Atomic state writes:** `forge-state.yaml` is written to a temp file then `mv`'d - correct pattern, avoids partial reads by agents
+- **Symlink protection:** `safe_move_task()` checks for and skips symlinks before task routing - good security practice
+- **Directory traversal protection:** Validates destination is within `FORGE_ROOT` before any file move
+- **Notification sanitization:** `sanitize_notification_message()` strips injection-dangerous chars before passing to `powershell.exe`/`osascript`/`notify-send`
+- **flock for startup:** Uses `flock -n 200` to prevent race condition when multiple daemon instances try to start simultaneously (falls back gracefully if flock unavailable)
+- **Adaptive polling:** Switches between 5s (active) and 30s (idle) intervals based on worker activity, reducing unnecessary I/O when nothing is happening
+- **SQLite persistence:** Agent status aggregated from JSON files into SQLite with mtime filtering - only re-reads files that changed
+- **SQL injection prevention:** `db_escape()` throughout, numeric validation on mtime/minutes/days before interpolating into queries
+- **Log rotation:** File-size-based rotation at 1MB, notification log trimming at 1000 entries
+- **Stale agent detection:** Agents not updated in 5 minutes flagged in dashboard; entries deleted after 30 minutes
+
+**Issues / Weaknesses:**
+
+1. **No daemon restart on crash.** If the daemon process dies (OOM, unhandled signal, disk error), there is no watchdog or `supervisord`/`systemd` unit to restart it. Users would see stale state with no indication the daemon stopped, only that status is stale.
+
+2. **`kill` for stop is not graceful.** `cmd_stop()` sends `kill $pid` (SIGTERM) then immediately removes the PID/lock files. If the daemon is mid-write to `forge-state.yaml`, the partial temp file `.tmp.$$` may be orphaned. Should wait for confirmation the process stopped.
+
+3. **Cross-platform `stat` for file mtime is fragile.** The daemon uses `stat -c %Y` (Linux) with fallback to `stat -f %m` (macOS). On MSYS2/Git Bash on Windows, `stat` behavior differs and the fallback `echo "0"` means the mtime check always fails, causing re-reads of all status files every iteration.
+
+4. **`date -d` for timestamp parsing is Linux-only.** `build_worker_status()` and `display_worker_status()` use `date -d "$updated"` to compute staleness. On macOS this requires `date -j -f` (BSD date). The fallback `echo "0"` means staleness is never detected on macOS. The `STALE_STATUS_THRESHOLD` logic is effectively dead on macOS.
+
+5. **Maintenance interval is iteration-count based, not time-based.** With adaptive polling, `MAINTENANCE_INTERVAL=100` iterations could mean 100 * 5s = 8.3 minutes (active) or 100 * 30s = 50 minutes (idle). This is inconsistent. Maintenance (log rotation, stale cleanup) should run on elapsed time.
+
+6. **No health endpoint.** There is no way for an external process or monitoring tool to query "is the daemon healthy?" Other than checking the PID file and log recency, there is no programmatic health check.
+
+7. **`status_history` table is populated nowhere.** `db_record_status_history()` exists but is never called in the daemon loop. The history table is created, indexed, and pruned - but it accumulates no data. This is dead infrastructure.
+
+8. **Windows PowerShell toast notification is fire-and-forget.** The spawned `powershell.exe` process for urgent notifications has no error handling. On systems where toast notifications are disabled (common in enterprise), the process silently fails. The `&` background discard is intentional but means notification failures are invisible.
+
+---
+
+## 3. Cross-Platform Support Assessment
+
+### Vibe Forge
+
+- `forge-setup.sh` detects MINGW/MSYS/CYGWIN for Windows, Darwin, Linux
+- Finds Git Bash via hardcoded path list + `where git` fallback
+- `util.sh` presumably has cross-platform `sed -i` helper (`sed_inplace`)
+- Multi-OS CI matrix validates `node bin/cli.js` works on all three platforms
+- Windows Terminal spawn support (`forge spawn`)
+
+**Known cross-platform gaps identified:**
+- `stat` for mtime (daemon): different flags on Linux vs macOS vs Git Bash
+- `date -d` (daemon staleness): Linux-only, broken on macOS
+- `flock`: Available on Linux, often missing on macOS (needs `brew install util-linux`) and Git Bash
+
+### BMAD
+
+- Pure Node.js - inherently more portable than bash
+- 25+ IDE platform targets defined in `platform-codes.yaml`
+- Explicit Windows stdin `error` event suppression
+- Path separators normalized (`replaceAll('\\', '/')`) before writing to files
+- `.nvmrc` pins Node 22 for reproducibility
+
+**Verdict:** BMAD's Node.js-first approach is more portable by default. Vibe Forge's bash-heavy implementation requires significant per-platform testing. The multi-OS CI matrix catches install failures but not runtime daemon behavior differences.
+
+---
+
+## 4. Automation Quality Assessment
+
+### Shell Scripts
+
+The Vibe Forge bin scripts are well-structured and security-conscious for bash. Key observations:
+
+**`bin/lib/database.sh`:**
+- Proper SQL injection prevention via `db_escape()`
+- Identifier validation (`db_validate_identifier()`)
+- Numeric validation before interpolation
+- Guard function `db_require_init()` prevents accidental uninitialized calls
+- SQLite `ON CONFLICT DO UPDATE` (upsert) pattern is correct
+
+**`bin/lib/constants.sh`:**
+- Centralized exit codes (following sysexits.h conventions)
+- Agent whitelist for security in `VALID_AGENTS`
+- Comprehensive aliases map
+- Well-commented, sync notes included
+- `STALE_STATUS_THRESHOLD=300` but the staleness check in the daemon is broken on macOS (see above)
+
+**`forge-setup.sh`:**
+- Non-interactive mode flag for CI/automation
+- Tech stack auto-detection from common project files
+- Cross-platform config written correctly
+- VCS detection via Node.js (`vcs.js`) rather than bash - smart choice for portability
+
+**Idempotency:** Setup is largely idempotent (checks if config/context already exists). Daemon start checks for running PID. Task routing uses `safe_move_task()` which checks existence. Generally good.
+
+**Error handling:** Scripts use `set -e`. Exit codes are standardized. Functions return meaningful codes. However, the daemon's `daemon_loop` traps `EXIT` but not `ERR` - an unhandled error in a loop iteration would not be logged before exit.
+
+---
+
+## 5. Monitoring and Observability
+
+### Vibe Forge
+
+- `forge-state.yaml` - task counts, worker statuses, attention alerts (pull-based, refreshed by daemon)
+- `context/agent-status/*.json` - per-agent status files (push-based, written by agents)
+- `.forge/daemon.log` - daemon activity log (rotated at 1MB)
+- `.forge/notifications.log` - human-readable notification history
+- SQLite status history table (schema exists, data never written - dead)
+- Platform-specific toast notifications for urgent alerts
+
+**Missing:**
+- No metrics (task throughput, avg completion time, worker utilization)
+- No structured logging (plain text, hard to parse/query)
+- No alerting on daemon death
+- No CI visibility into per-agent performance over time
+- The `status_history` table would provide all of this if actually populated
+
+### BMAD
+
+- Discord webhook for release/PR/issue events (external visibility)
+- `--debug` flag for manifest generation tracing
+- npm version check on CLI startup
+- Verbose clack/prompts output during install
+
+BMAD has no operational monitoring (no daemon to monitor). Its observability is release-event-driven, not runtime-operational.
+
+---
+
+## 6. Container Support
+
+### Vibe Forge
+
+None. No Dockerfile, no `docker-compose.yml`, no container references anywhere.
+
+### BMAD
+
+None. By design - purely a CLI + Markdown content package.
+
+**Assessment for Vibe Forge:** Container support is not clearly needed yet. The forge runs on developer workstations, not in servers. However, a `Dockerfile` for the daemon would enable:
+- Running the forge backend in CI environments without a full developer machine
+- Reproducible daemon environment (solves cross-platform bash issues)
+- Future hosted/SaaS mode
+
+This is a future concern, not a current gap.
+
+---
+
+## 7. Environment Management
+
+### Vibe Forge
+
+- `.forge/config.json` stores platform, git bash path, vcs type, validated flag, daemon/worker-loop preferences
+- `context/project-context.md` holds project-specific context for agents
+- No `.env` file pattern
+- No environment variable management beyond `CLAUDE_CODE_GIT_BASH_PATH`
+- Node version not pinned (no `.nvmrc`)
+- npm version pinned in `publish.yml` but not project-wide
+
+### BMAD
+
+- Node version pinned to 22 via `.nvmrc`
+- npm `engines` field in `package.json` (`>=20.0.0`)
+- Installation options stored in project config, not environment variables
+- No secrets management (no server-side runtime)
+
+**Gap: No `.nvmrc`/`engines` in Vibe Forge.** If a contributor's local Node differs from the CI Node (`20` in CI currently), subtle incompatibilities can emerge. The CI uses Node 20 but nothing enforces this locally.
+
+---
+
+## 8. Release Automation (Herald Comparison)
+
+### Vibe Forge Herald
+
+Herald is described as the Release Manager agent. Its personality handles deployment and release coordination. The `publish.yml` workflow handles the technical publication to npm.
+
+Current release flow:
+1. Manual GitHub Release creation triggers `publish.yml`
+2. Workflow validates optional version input (semver)
+3. Bumps version if provided
+4. Publishes to npm with provenance
+5. Verifies npm availability after 30s
+
+### BMAD Release Flow
+
+1. Automatic `@next` prerelease on every main push (touching source)
+2. Manual `workflow_dispatch` promotes to `@latest`
+3. Version computed from npm registry (not just package.json)
+4. Commits version bump + creates git tag using GitHub App token (bypasses branch protection)
+5. Generates GitHub Release from `CHANGELOG.md` section
+6. Discord notification to community
+
+**Gaps in Vibe Forge:**
+- No `@next` / prerelease channel
+- No automatic CHANGELOG-to-Release-notes extraction
+- No git tag creation in CI (manual tagging required)
+- No community notification on release
+- Verify step uses `sleep 30` which is fragile (npm propagation can take longer)
+
+---
+
+## 9. Summary: Gaps and Recommendations
+
+### P1 - High Impact, Low Effort
+
+1. **Add `.nvmrc` and `engines` field to `package.json`** - Pin Node version for reproducibility. CI uses Node 20; enforce it locally too.
+
+2. **Add `markdownlint` to CI** - All agent personalities, task templates, and docs are Markdown. Currently zero lint coverage on them. `markdownlint-cli2` is easy to add as a parallel job.
+
+3. **Fix `date -d` macOS incompatibility in daemon** - The staleness detection in `build_worker_status()` and `display_worker_status()` is dead on macOS due to BSD `date` syntax. This silently breaks a key monitoring feature.
+
+4. **Fix `stat` mtime on Git Bash/Windows in daemon** - The mtime comparison for status file change detection always falls back to `0` on Windows Git Bash, causing the daemon to re-read and re-sync all agent status files on every iteration.
+
+5. **Wire up `db_record_status_history()`** - The history table schema, index, and pruning are all implemented but `db_record_status_history()` is never called. Call it in `db_upsert_agent_status()` to enable metrics. One line of change, unlocks task throughput and worker utilization analytics.
+
+### P2 - High Impact, Medium Effort
+
+6. **Add Husky pre-commit hooks** - Mirror CI checks locally (format, lint, shellcheck). Catches issues before push. Reduces CI feedback loop from minutes to seconds.
+
+7. **Add `@next` prerelease channel** - Automatic prerelease on main push. Allows testing of new agent/skill changes without touching `@latest`. Reduces risk of publishing broken releases to users.
+
+8. **Add prettier/formatting enforcement to CI** - Currently only shellcheck runs. JavaScript and Markdown files have no formatting gate. Inconsistent formatting accumulates over time.
+
+9. **Add daemon watchdog** - If the daemon crashes, workers continue writing status files but routing and state updates stop silently. A simple watchdog (cron or supervisor) that checks the PID and restarts the daemon would prevent invisible failures.
+
+### P3 - Medium Impact, Medium Effort
+
+10. **Maintenance interval: time-based, not iteration-based** - Replace `MAINTENANCE_INTERVAL=100` counter with an epoch-based last-maintenance timestamp check. This makes maintenance behavior predictable regardless of adaptive polling rate.
+
+11. **Graceful daemon stop** - `cmd_stop()` should wait for the daemon process to exit (with timeout) before removing PID/lock files, rather than fire-and-forget SIGTERM.
+
+12. **Add CHANGELOG-to-Release extraction in `publish.yml`** - Generate GitHub Release body from CHANGELOG automatically instead of requiring manual release notes. BMAD does this cleanly.
+
+13. **Structured daemon logging** - Replace plain-text daemon log with structured JSON lines. Enables future log analysis, metrics extraction, and tooling integration.
+
+### P4 - Lower Priority / Future
+
+14. **Discord/webhook release notifications** - Community transparency on releases. BMAD does this; adds engagement signal.
+15. **CodeRabbit or equivalent AI PR review** - Automated first-pass review on PRs.
+16. **Dockerfile for daemon** - Enables CI/hosted mode, solves cross-platform bash issues.
+17. **npm `@next` install docs** - If `@next` channel is added, document how to opt in.
+
+---
+
+## Acceptance Criteria Status
+
+- [x] Read all relevant scripts and CI configs
+- [x] Fetch and review BMAD repo
+- [x] Identify daemon/orchestration improvements
+- [x] Assess CI/CD gaps
+- [x] Write findings to tasks/review/bmad-review-ember.md

package/tasks/review/bmad-review-furnace.md

@@ -0,0 +1,285 @@
+---
+id: bmad-review-furnace
+title: "BMAD vs Vibe Forge: Backend/Infrastructure Review"
+completed_by: furnace
+completed_at: 2026-03-31T00:00:00Z
+epic: BMAD-REVIEW
+---
+
+# BMAD vs Vibe Forge: Backend/Infrastructure Findings
+
+Reviewed by: Furnace
+Date: 2026-03-31
+Focus: Backend agent, task data model, API scaffolding, data flow, error handling, daemon/orchestration
+
+---
+
+## 1. Backend Agent Comparison: Furnace vs BMAD's Amelia
+
+### BMAD's Approach
+
+BMAD has **one generalist dev agent - Amelia** (`bmad-agent-dev`). She handles all code: frontend, backend, database, CLI. There is no frontend/backend split. Her skills are:
+- `DS` - Develop story (implement a story end-to-end)
+- `CR` - Code review
+
+Supporting Amelia is **Bob (Scrum Master)** who owns story creation and fills in the Dev Notes section with architecture guardrails, relevant file paths, and tech constraints before Amelia ever touches code. This front-loading is explicit and enforced.
+
+### Vibe Forge's Approach
+
+Furnace is domain-specialized (backend only). This is structurally sound for parallel multi-agent work but creates gaps:
+
+**What BMAD does that Furnace doesn't:**
+
+1. **No pre-implementation story enrichment.** BMAD's create-story workflow (Bob) loads the full PRD, epics, architecture docs, and UX designs before writing the story. The resulting story file contains a "Dev Notes" section with:
+   - Architecture guardrails the dev MUST follow
+   - Relevant source tree paths to touch
+   - Testing standards summary
+   - Cross-referenced citations to architecture docs
+
+   Vibe Forge tasks have a "Relevant Files" section but no enforced architecture-grounding step. Agents receive tasks that may lack critical context.
+
+2. **No "Dev Agent Record" on completed work.** BMAD story files track:
+   - Agent model version used
+   - Completion notes
+   - Debug log references
+   - **Full file list** (every file changed)
+
+   Vibe Forge completion summaries have `files_modified` and `files_created` but no model version tracking and no debug log refs.
+
+3. **No HALT condition protocol.** BMAD's dev-story workflow defines explicit halt conditions:
+   - New external dependency required
+   - 3 consecutive failures on same test
+   - Missing or conflicting configuration
+   - Ambiguous requirements
+
+   Furnace just has "report blocked" with no structured criteria.
+
+4. **Strict TDD enforcement.** BMAD mandates red-green-refactor per task/subtask. Writing the failing test before implementation is a workflow step, not a guideline. Vibe Forge's patterns suggest TDD but don't enforce the sequence at the workflow level.
+
+**What Furnace does better:**
+
+- Domain ownership is explicit. Clear boundaries prevent agents from stepping on each other.
+- Security consciousness is baked in (auth, validation, sanitization as principles).
+- Result type pattern for error handling (`Result<T, E>`) is production-grade.
+
+**Gap severity: High.** Missing story enrichment means Furnace may implement against wrong architecture assumptions.
+
+---
+
+## 2. Task Data Model Comparison
+
+### Vibe Forge Task (config/task-template.md)
+
+```
+id, title, type, priority, status, assigned_to, blocked_by, depends_on,
+estimated_complexity, epic, story (optional)
+```
+
+Body sections: Context, Relevant Files, Dependencies, Background, Acceptance Criteria, Agent Instructions, Output Expected, Completion Summary.
+
+### BMAD Story Template
+
+```
+Story N.M: Title
+Status: (inline, not frontmatter)
+
+## Story (user story format: As a / I want / So that)
+## Acceptance Criteria (numbered, not checkboxes)
+## Tasks / Subtasks (checkbox tree with AC references)
+## Dev Notes (architecture refs, path refs, testing standards)
+## Dev Agent Record (model version, debug logs, file list, completion notes)
+```
+
+### Gap Analysis
+
+| Dimension | Vibe Forge | BMAD | Gap |
+|---|---|---|---|
+| Routing metadata | ✅ type, assigned_to | ❌ none (human routes) | VF wins |
+| Dependency tracking | ✅ blocked_by, depends_on | ❌ none in story | VF wins |
+| Architecture grounding | ❌ optional background | ✅ Dev Notes (enforced) | BMAD wins |
+| File list tracking | Partial (in completion) | ✅ per-task in Dev Agent Record | BMAD wins |
+| Agent model versioning | ❌ missing | ✅ tracked | BMAD wins |
+| User story framing | ❌ missing | ✅ As a/I want/So that | BMAD wins |
+| Task/subtask tree | ❌ AC only | ✅ Tasks -> Subtasks with AC refs | BMAD wins |
+| Completion checklist | Informal | ✅ formal checklist.md | BMAD wins |
+| SLA / complexity timing | ✅ estimated_minutes per type | ❌ none | VF wins |
+| Numeric story ordering | ❌ none | ✅ epic_num.story_num | BMAD wins |
+
+**Three specific improvements to add:**
+
+1. **Add `tasks` section to task template** - a checkbox tree where each task maps to one or more AC items. BMAD's `- [ ] Task 1 (AC: #1)` format gives explicit AC traceability per implementation unit.
+
+2. **Add `dev_notes` section** - architecture guardrails, relevant source paths, tech constraints. Should be filled by Hub/Architect before assignment, not left to the implementing agent to discover.
+
+3. **Add `file_list` to Completion Summary** - every file created or modified, not just "files_created" and "files_modified" aggregates. This feeds Sentinel review and future metrics.
+
+---
+
+## 3. API/Service Project Scaffolding
+
+### BMAD
+
+BMAD has `bmad-create-architecture` (Winston) which generates architecture documents before implementation begins. The `bmad-create-story` workflow then explicitly loads these architecture docs and injects relevant constraints into the story's Dev Notes. The flow is:
+
+```
+Winston creates architecture doc -> Bob reads it when creating stories ->
+Dev Notes contain specific file paths, patterns, and constraints ->
+Amelia implements against grounded instructions
+```
+
+BMAD also has `bmad-generate-project-context` for brownfield projects - generates a `project-context.md` that all agents load.
+
+### Vibe Forge
+
+Furnace owns `/src/api/**`, `/src/services/**`, `/src/models/**`, `/src/middleware/**`, but:
+- No scaffolding workflow exists
+- No architecture-to-task injection pipeline
+- `project-context.md` exists as a template but is populated manually
+- No dedicated Architect agent that runs before implementation tasks are created (there is an `architect` agent in constants.sh but no corresponding task creation workflow)
+
+**Specific gap:** Tasks arrive at Furnace without guaranteed architecture grounding. If the Architect agent defined `Result<T, E>` as the service layer pattern, that constraint should appear in every backend task's Dev Notes - not discovered by Furnace via convention.
+
+**Improvement:** The Hub's task creation flow should have a step that loads architecture docs and injects relevant patterns into `dev_notes` before assigning to Furnace. This is workflow infrastructure, not just documentation.
+
+---
+
+## 4. Data Flow Between Agents
+
+### Vibe Forge
+
+```
+Task file created in tasks/pending/
+-> Daemon detects, notifies
+-> Agent picks up, moves to tasks/in-progress/
+-> Agent completes, moves to tasks/completed/
+-> Daemon auto-routes to tasks/review/
+-> Sentinel reviews, moves to tasks/approved/ or tasks/needs-changes/
+-> Daemon auto-routes approved to tasks/merged/
+```
+
+State is distributed: task files carry status, `context/agent-status/*.json` tracks live agent state, SQLite aggregates both.
+
+### BMAD
+
+```
+sprint-status.yaml is the single coordination file
+-> Agents read it to find next ready-for-dev story
+-> Agent updates status in the file on start and completion
+-> Human mediates agent transitions
+```
+
+No daemon. State is centralized in one YAML file. No automated routing.
+
+### Gap Analysis
+
+**Where Vibe Forge wins:** Fully automated routing. Agents don't need to manually poll or coordinate. The daemon handles task lifecycle transitions. OS-level notifications. SQLite metrics.
+
+**Where BMAD wins:**
+
+1. **Sprint-status.yaml is a queryable state contract.** Any agent can inspect the full project's implementation state (all stories, all epics, backlog through done) from one file. Vibe Forge has no equivalent cross-task state view. `forge-state.yaml` has counts but not per-task status.
+
+2. **Stories carry forward learnings.** The create-story workflow reads previous story files when creating new ones, allowing accumulated implementation notes to inform the next story's Dev Notes. Vibe Forge tasks are independent - no mechanism to forward learnings between tasks.
+
+3. **Dependency resolution at story creation time.** By grounding stories in architecture docs before dev starts, BMAD reduces mid-task blockers. Vibe Forge tasks can arrive with unresolved architecture questions.
+
+**Specific improvement:** Add a `context/sprint-state.yaml` that tracks per-task status, not just counts. The daemon should write task-level status entries (id, assigned_to, status, updated) when it routes tasks. This gives agents a single file to query: "what's in-progress? what just completed? what's blocked?"
+
+---
+
+## 5. Error Handling and Failure Patterns
+
+### BMAD
+
+BMAD's dev-story workflow defines explicit **HALT conditions** - circumstances where the agent must stop and request human input:
+
+- New external dependency required (package not in project)
+- 3 consecutive test failures on the same test
+- Configuration is missing or contradictory
+- Story requirements are ambiguous or contradictory
+
+BMAD also has a formal **Definition of Done checklist** (`checklist.md`) with explicit gates across: context, implementation, testing, documentation, and final status. The agent cannot self-declare completion without satisfying the checklist.
+
+### Vibe Forge
+
+- `blocked` status exists but HALT criteria are undefined
+- `/need-help` skill creates an attention file but no formal trigger conditions
+- No Definition of Done checklist - completion is declared via agent-written summary
+- No maximum retry / escalation policy
+
+**Three specific improvements:**
+
+1. **Define HALT criteria in agent personality files.** Furnace should have an explicit list: "HALT and report blocked if: (a) required package not in package.json, (b) schema change needed that affects live data, (c) DB migration would be destructive, (d) auth pattern conflicts with existing middleware, (e) 3 consecutive test failures on same test."
+
+2. **Add a formal Definition of Done checklist** to `config/task-template.md`. Minimal for backend tasks:
+   - [ ] All acceptance criteria checked
+   - [ ] Unit tests written and passing
+   - [ ] Integration tests written and passing
+   - [ ] No linting errors
+   - [ ] File list complete in completion summary
+   - [ ] No hardcoded secrets
+   - [ ] Error paths handled (not swallowed)
+   - [ ] DB migration safe (no data loss without explicit warning)
+
+3. **Add escalation timeout.** If a task stays in `tasks/in-progress/` for longer than `estimated_minutes * 3`, the daemon should auto-escalate to `tasks/attention/`. Currently there is no time-based escalation.
+
+---
+
+## 6. Daemon/Orchestration Gap
+
+### Vibe Forge Daemon Strengths
+
+The daemon is a genuine competitive advantage over BMAD:
+- Automated task routing (completed -> review, approved -> merged)
+- Adaptive polling (active: 5s, idle: 30s)
+- SQLite state persistence with mtime-filtered sync
+- OS-level toast notifications (Windows/macOS/Linux)
+- Agent status staleness detection
+- Log rotation and maintenance
+- Symlink attack prevention, path traversal protection
+
+BMAD has none of this - it is 100% human-mediated.
+
+### Daemon Gaps
+
+1. **No dependency resolution.** The daemon moves all completed tasks to review regardless of downstream task dependencies. If Task B depends on Task A, Task B should stay in pending until Task A is merged. The `depends_on` and `blocked_by` fields in the task frontmatter exist but the daemon does not act on them.
+
+2. **No time-based escalation.** Tasks can stall in `tasks/in-progress/` indefinitely. The daemon tracks `updated_at` per agent but does not correlate agent work duration against task `estimated_complexity`.
+
+3. **No dead-letter queue.** If a task file becomes corrupted or unparseable, the daemon logs a warning and moves on. There is no `tasks/failed/` folder for tasks that have errored out permanently.
+
+4. **No metrics API.** `status_history` table is populated but never surfaced. There is no way to query: average task completion time, which agents are slowest, task failure rates. The data exists, the query layer does not.
+
+5. **No cross-task sprint state.** As noted above, `forge-state.yaml` has counts but not per-task status. An agent cannot ask the daemon "what tasks are currently in-progress for the current epic?"
+
+6. **Completed tasks bypass review for this task type.** The task is type `review` but it gets auto-routed by the daemon to `tasks/review/` on completion. Review tasks routing to review creates a loop. The daemon should respect `task_types.yaml` `auto_assign: true` flags and not re-queue tasks that are themselves review outputs.
+
+---
+
+## Summary: Priority Improvements
+
+| Priority | Gap | Effort |
+|---|---|---|
+| HIGH | Add `dev_notes` to task template (architecture guardrails, relevant paths) | Low |
+| HIGH | Add `tasks` subtask tree to task template (with AC refs) | Low |
+| HIGH | Define HALT criteria per agent personality | Low |
+| HIGH | Add formal DoD checklist to task template | Low |
+| MEDIUM | Daemon: time-based escalation for stale in-progress tasks | Medium |
+| MEDIUM | Daemon: dependency resolution (hold tasks with unresolved depends_on) | Medium |
+| MEDIUM | Add `context/sprint-state.yaml` with per-task status (daemon-maintained) | Medium |
+| MEDIUM | Add `file_list` to completion summary (not just created/modified split) | Low |
+| LOW | Daemon: dead-letter queue (tasks/failed/) | Medium |
+| LOW | Daemon: surface status_history as metrics endpoint | Medium |
+
+---
+
+## Files Reviewed
+
+- `agents/furnace/personality.md`
+- `bin/forge-daemon.sh`
+- `bin/lib/database.sh`
+- `bin/lib/constants.sh`
+- `config/task-template.md`
+- `config/task-types.yaml`
+- BMAD repo: `src/bmm-skills/` (all phases, fetched via GitHub API)
+- BMAD: `bmad-agent-dev`, `bmad-agent-sm`, `bmad-dev-story`, `bmad-create-story` workflows
+- BMAD: `module.yaml`, story template, checklist.md