@pjmendonca/devflow 1.13.2 → 1.19.0

package/.claude/skills/validate/SKILL.md

@@ -0,0 +1,101 @@
+# Validate Skill
+
+Run automated validation checks with feedback loops.
+
+## Description
+
+The validate skill runs a three-tier validation system:
+
+1. **Pre-flight** (Tier 1): Checks before execution
+   - Story file exists
+   - Budget is available
+   - Dependencies are valid
+
+2. **Inter-phase** (Tier 2): Checks between agents
+   - Code compiles/parses
+   - Linting passes
+   - Phase transitions are valid
+
+3. **Post-completion** (Tier 3): Checks after pipeline
+   - Tests pass
+   - Types are valid
+   - Version is synced
+   - Changelog is updated
+
+## Usage
+
+```
+/validate [story-key] [--tier 1|2|3|all] [--auto-fix] [--json]
+```
+
+## Arguments
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| story-key | Story identifier to validate | Current branch |
+| --tier | Validation tier (1, 2, 3, or all) | all |
+| --auto-fix | Attempt automatic fixes | false |
+| --json | Output as JSON | false |
+| --quiet | Minimal output | false |
+
+## Examples
+
+### Run all validations
+```
+/validate 3-5 --tier all
+```
+
+### Run post-completion checks with auto-fix
+```
+/validate --tier 3 --auto-fix
+```
+
+### Get JSON output for CI
+```
+/validate 3-5 --json
+```
+
+## Prompt
+
+You are running validation checks for the Devflow project.
+
+$ARGUMENTS
+
+Execute the validation loop:
+
+```python
+import sys
+sys.path.insert(0, "tooling/scripts/lib")
+
+from validation_loop import (
+    create_validation_loop,
+    run_preflight_validation,
+    run_post_completion_validation,
+    ALL_GATES,
+    LoopContext,
+)
+
+# Parse arguments
+story_key = "$ARGUMENTS".split()[0] if "$ARGUMENTS" else "validation-check"
+tier = "all"  # Default to all tiers
+
+# Create context
+context = LoopContext(story_key=story_key)
+
+# Run appropriate validation
+if tier == "1" or tier == "all":
+    print("[VALIDATION] Running pre-flight checks...")
+    report = run_preflight_validation(story_key)
+    print(report.to_summary())
+
+if tier == "3" or tier == "all":
+    print("[VALIDATION] Running post-completion checks...")
+    report = run_post_completion_validation(story_key)
+    print(report.to_summary())
+```
+
+Report results clearly with:
+- [PASS] for passed gates
+- [WARN] for warnings
+- [FAIL] for failures
+- Suggested fixes when available

package/CHANGELOG.md

@@ -5,6 +5,290 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.19.0] - 2026-01-03
+
+### Added
+- **Story Discovery Phase in Init Wizard** - Optional Phase 4 for quick story brainstorming
+  - Vision discovery with problem, users, success metrics, and competitive advantage
+  - Core feature identification with comma-separated input
+  - First sprint planning with story proposals
+  - Automatic story file generation in `tooling/docs/stories/`
+  - Integration with sprint-status.yaml for backlog tracking
+
+- **Brainstorm Skill** - Full workshop for product discovery and story creation
+  - `/brainstorm` command for 30-minute comprehensive workshops
+  - `--quick` mode for 10-minute vision + features session
+  - `--journey` mode for focused user journey mapping
+  - `--features` mode for rapid feature brainstorming
+  - `--decompose EPIC` to break epics into stories
+  - `--prioritize` to re-prioritize existing backlog
+
+- **Brainstorming Techniques Guide** - Reference documentation for discovery methods
+  - Guided Discovery (Socratic method) with vision and feature questions
+  - User Journey Mapping with 5-stage framework (Trigger, Entry, Core, Success, Retention)
+  - Rapid Feature List with MoSCoW prioritization
+  - Story Decomposition with INVEST criteria
+  - RICE scoring and Impact/Effort matrix for prioritization
+
+- **Story Template** - New `tooling/docs/templates/story.md` for feature stories
+  - User story format with acceptance criteria
+  - Priority and effort sizing (XS/S/M/L/XL)
+  - Technical notes, business rules, and dependencies
+  - Testing strategy and definition of done
+
+- **Stories Directory** - `tooling/docs/stories/` for story file storage
+  - Stories use format: `STORY-{sprint}-{number}-{slug}.md`
+  - Integrated with sprint-status.yaml tracking
+
+### Changed
+- **Init Wizard** - Now 6 phases (added Story Discovery as Phase 4)
+  - Quick Mode skips story discovery, recommends `/brainstorm` after setup
+  - Phase 6 summary includes story count and brainstorm command reference
+  - Directory structure now includes `tooling/docs/stories/` and `tooling/docs/templates/`
+
+## [1.18.0] - 2025-12-30
+
+### Added
+- **Adversarial Swarm Mode** - Multi-agent debates with opposing personas for robust designs
+  - `personality_system.py` - Dynamic persona selection and adversarial stance management
+  - `PersonalitySelector` - Analyzes tasks and selects opposing personas automatically
+  - `ConvergenceDetector` - Hybrid convergence detection (position stability + token budget)
+  - `PersonalityHandoff` - Structured handoff with debate summary for implementing agent
+  - Agents assigned adversarial stances that naturally oppose each other
+  - Cross-challenge prompts force agents to defend positions and find edge cases
+  - Automatic consensus/convergence detection ends debates efficiently
+
+- **Adversarial Stance Templates** - Added `adversarial_stance` to persona templates
+  - `primary_concern` - Agent's core focus (security, velocity, simplicity, etc.)
+  - `opposes` - Stances this persona naturally challenges
+  - `challenge_triggers` - Phrases that trigger pushback
+  - `debate_style` - How the agent argues (assertive, questioning, evidence-based)
+  - Updated templates: thorough-critic, security-focused, rapid-prototyper,
+    quick-sanity, enterprise-architect, pragmatic-minimalist, performance-engineer
+
+- **New Persona Templates** for better adversarial coverage
+  - `dev/user-advocate.yaml` - UX-focused developer who champions end users
+  - `maintainer/reliability-engineer.yaml` - Reliability/SRE perspective on failure modes
+
+- **Test Harness for Swarm Performance** - Benchmark and analyze debate effectiveness
+  - `test_adversarial_swarm.py` - Simulated testing without LLM calls
+  - Tracks per-round metrics: new arguments, challenges, concessions, agreement
+  - Calculates marginal value per round to identify diminishing returns
+  - Generates performance plots (matplotlib) showing trends over rounds
+  - Saves benchmark results to `tooling/.automation/benchmarks/`
+
+### Changed
+- **SwarmOrchestrator** - Now adversarial by default
+  - Prompts restructured for debate format with cross-challenges
+  - Agents receive opponent positions and must respond to challenges
+  - Concession tracking for convergence detection
+  - PersonalityHandoff generated with consensus points and unresolved tensions
+
+## [1.17.0] - 2025-12-29
+
+### Added
+- **Usage Projection & Forecasting** - Predict when subscription limits will be reached
+  - `cost_tracker.py` - `get_usage_projection()` calculates daily averages and forecasts
+  - Dashboard shows "At current rate, limit reached in X days" warnings
+  - Displays projected end-of-period usage vs limit
+  - Color-coded on-track/warning/critical status
+- **Model Efficiency Metrics** - Cost-per-output-token analysis
+  - `cost_tracker.py` - `get_model_efficiency()` ranks models by efficiency
+  - `cost_dashboard.py` - `--efficiency` / `-E` flag to display metrics
+  - Shows: $/1K output tokens, output/input ratio, calls, total cost
+  - Highlights most cost-efficient model with [BEST] badge
+- **Subscription Plan Presets** - Easy configuration with common plans
+  - `cost_config.py` - `SUBSCRIPTION_PLANS` with free/developer/pro/scale/enterprise
+  - `--set-plan` CLI flag to configure and persist plan
+  - Environment variable: `SUBSCRIPTION_PLAN=pro`
+  - Auto-saves to config.json for persistence
+- **Analytics Export System** - Comprehensive reports with trends and rankings
+  - `--schedule-export` flag generates full analytics report
+  - Daily usage trends (last 14 days with tokens, cost, sessions)
+  - Per-story cost rankings (top 10 by token consumption)
+  - Period comparison (current vs previous period with deltas)
+  - API rate statistics (calls/day, calls/hour, peak times)
+  - Export formats: JSON (full data), Markdown (formatted report)
+- **API Rate Tracking** - Monitor API call patterns
+  - `cost_tracker.py` - `get_api_rate_stats()` for call frequency analysis
+  - Tracks: total calls, calls per day/hour, peak hour, peak day
+  - Hourly and daily distribution data for pattern analysis
+
+## [1.16.0] - 2025-12-29
+
+### Added
+- **Subscription Usage Tracking** - Track token usage against API subscription limits
+  - `cost_config.py` - New `subscription_token_limit` and `subscription_billing_period_days` settings
+  - `cost_tracker.py` - `get_subscription_usage()` and `get_subscription_percentage()` methods
+  - `cost_dashboard.py` - `--subscription` / `-S` flag to display subscription usage
+  - Environment variable support: `SUBSCRIPTION_TOKEN_LIMIT`, `SUBSCRIPTION_BILLING_PERIOD_DAYS`
+  - Progress bar visualization with color-coded status (ok/warning/critical/exceeded)
+  - Subscription summary included in `--summary` view when configured
+  - Tracks: used tokens, remaining tokens, percentage, billing period, total cost
+
+## [1.15.0] - 2025-12-29
+
+### Added
+- **Context Monitor** - Real-time context window tracking and compaction awareness
+  - `lib/context_monitor.py` - Core context monitoring with threshold detection
+  - Tracks token usage and estimates context window consumption
+  - Five-level threshold system: SAFE, CAUTION, WARNING, CRITICAL, EMERGENCY
+  - Automatic checkpoint triggers at critical thresholds
+  - Activity tracking (current agent, phase, task) for status display
+- **Persistent Status Line** - Always-visible CLI status during operations
+  - Shows: Agent, Phase, Context%, Cost, Time in compact format
+  - Color-coded context indicators based on usage level
+  - Phase progress display (e.g., "[2/3] DEV Development (0:45)")
+  - Proactive warnings before compaction thresholds
+- **Status Line Integration** - Added to story runner
+  - `run-story.py` - Integrated context monitor with cost tracking
+  - Real-time status updates during phase execution
+  - Auto-checkpoint at critical/emergency context levels
+- **Unit Tests** - Comprehensive test coverage
+  - `tests/test_context_monitor.py` - 38 tests for context monitoring
+
+### Changed
+- **NativeRunner** - Now includes context monitoring alongside cost tracking
+- **.gitignore** - Added context and checkpoint directories for user-specific data
+
+## [1.14.0] - 2025-12-29
+
+### Added
+- **Validation Loop Framework** - Three-tier automated feedback and validation system
+  - `lib/validation_loop.py` - Core validation engine with configurable gates
+  - Tier 1 (Pre-flight): Story exists, budget available, dependencies valid
+  - Tier 2 (Inter-phase): Code compiles, lint passes, phase transitions
+  - Tier 3 (Post-completion): Tests pass, types valid, version synced
+  - Auto-fix capability for lint and formatting issues
+  - Validation history tracking in shared memory/knowledge graph
+- **Validation Integration** - Added to all agent pipelines
+  - `run-story.py` - Pre-flight, inter-phase, and post-completion validation
+  - `run-collab.py` - Pre-flight and post-completion validation
+  - `swarm_orchestrator.py` - Inter-iteration validation
+  - `pair_programming.py` - Inter-revision validation
+- **Validation CLI** - New command and skill for running validation
+  - `/validate` command in `.claude/commands/validate.md`
+  - Validate skill in `.claude/skills/validate/SKILL.md`
+  - Standalone script `tooling/scripts/validate_loop.py` for CI/CLI usage
+- **Validation Configuration** - YAML-based configuration
+  - `tooling/.automation/validation-config.yaml` - Gate configuration
+  - Per-gate overrides for timeouts, commands, and auto-fix
+- **CI Integration** - Validation in CI/CD pipeline
+  - New `validation-loop` job in `.github/workflows/ci.yml`
+  - Pre-commit hooks for validation in `.pre-commit-config.yaml`
+- **Unit Tests** - Comprehensive test coverage
+  - `tests/test_validation_loop.py` - Tests for validation system
+
+### Changed
+- **SwarmConfig** - Added `validation_enabled` flag (default: true)
+- **PairConfig** - Added `validation_enabled` flag (default: true)
+
+## [1.13.6] - 2025-12-29
+
+### Fixed
+- **Logic Bug in Prompt Sanitization** - Fixed always-true condition in `_sanitize_prompt()`
+  - `swarm_orchestrator.py` - Condition `(ord(char) >= 32 or ord(char) >= 128)` was always true
+  - `pair_programming.py` - Same bug fixed
+  - Now correctly filters control characters while preserving printable content
+- **Environment Variable Validation** - Added safe parsing in `cost_config.py`
+  - `from_env()` now uses `_safe_float()` and `_safe_int()` helpers
+  - Invalid values are logged and defaults are used instead of crashing
+- **Module-level Import** - Moved `import re` to module level in `cost_tracker.py`
+  - Was previously inside `parse_token_usage()` function
+  - Improves import time consistency
+
+## [1.13.5] - 2025-12-29
+
+### Added
+- **Subprocess Sanitization** - Security hardening for agent invocations
+  - `swarm_orchestrator.py` - Added `_sanitize_prompt()` for safe subprocess execution
+  - `pair_programming.py` - Same sanitization to prevent injection attacks
+  - Removes null bytes, control characters, and enforces length limits
+- **Pricing Cache** - Performance optimization for cost calculations
+  - `cost_tracker.py` - Added `_get_pricing()` with model lookup caching
+  - Eliminates repeated dictionary iterations for same models
+
+### Fixed
+- **Dead Code** - Removed unused code paths in `run-collab.py`
+  - Fixed unused `prompt` variable (was discarded f-string)
+  - Now captures and reports `run_sequential_mode()` return value
+- **Input Validation** - Added type validation in `cost_tracker.py`
+  - `calculate_cost()` now validates token inputs are numeric
+  - Raises `CalculationError` with helpful message for invalid inputs
+- **Negative Padding Crash** - Fixed crash in `cost_display.py`
+  - `_content_line()` now truncates content if too long
+  - Prevents negative padding that caused display errors
+- **Atomic File Writes** - Prevent config corruption in `currency_converter.py`
+  - `save_config()` now writes to temp file first, then atomic rename
+  - Cleans up temp file on failure
+
+### Changed
+- **Configurable Constants** - Extracted hardcoded values in `agent_router.py`
+  - `CONFIDENCE_BASE`, `CONFIDENCE_PATTERN_WEIGHT`, `CONFIDENCE_FILE_CONTEXT_WEIGHT`
+  - `COMPLEXITY_SIMPLE_THRESHOLD`, `COST_OPT_COMPLEXITY_THRESHOLD`, `MAX_ALTERNATIVES`
+- **Pre-compiled Patterns** - Performance optimization in `agent_router.py`
+  - `COMPILED_TASK_PATTERNS` - Pre-compiled regex for task type detection
+  - Faster pattern matching in `analyze_task()` method
+
+## [1.13.4] - 2025-12-27
+
+### Added
+- **Pre-commit Configuration** - New `.pre-commit-config.yaml` for automated code quality
+  - Ruff linting and formatting
+  - MyPy type checking
+  - Shell script linting with shellcheck
+  - General file hygiene (trailing whitespace, YAML/JSON validation)
+- **Agent Router Tests** - Comprehensive test suite for `agent_router.py`
+  - Tests for task type detection, complexity estimation, routing logic
+  - Tests for workflow selection and alternative agent suggestions
+
+### Fixed
+- **Bare Exception Handling** - Replaced broad `except Exception` with specific types
+  - `cost_config.py` - Now catches `json.JSONDecodeError` and `OSError` separately
+  - `currency_converter.py` - Now catches `json.JSONDecodeError` and `OSError` separately
+  - `agent_handoff.py` - Git operations now catch `subprocess.SubprocessError`
+- **Silent Failures** - Added warning messages to previously silent catch blocks
+  - `shared_memory.py` - Now logs warnings for corrupted memory/knowledge graph files
+  - `agent_handoff.py` - Now logs warnings when git operations fail
+- **Regex Performance** - Pre-compiled regex patterns in `memory_summarize.py`
+
+### Changed
+- **Environment Variables** - Standardized on `os.getenv()` across all files
+  - Updated `colors.py`, `cost_display.py`, `run-collab.py`
+  - Consistent pattern for environment variable access
+
+## [1.13.3] - 2025-12-27
+
+### Added
+- **Shared Python Libraries** - New reusable modules in `lib/`
+  - `colors.py` - Consolidated ANSI color codes with cross-platform support
+  - `platform.py` - Unified platform detection utilities
+- **Agent Improvements** - Enhanced all agent definitions
+  - Added "When Complete" sections to ARCHITECT, MAINTAINER, BA, PM, WRITER agents
+  - Added "Context Management" sections to all agents missing them
+- **Command Documentation** - Expanded command help files
+  - Enhanced `/bugfix` with workflow description and options
+  - Enhanced `/devflow` with full command reference table
+  - Enhanced `/review` with verdict explanations and options
+
+### Fixed
+- **JavaScript Bug** - Fixed no-op ternary in `lib/exec-python.js:53-55` that did nothing
+- **Stale Reference** - Removed orphaned `devflow-init` from `lib/constants.js`
+- **Error Handling** - Added error handler to `spawn()` in `bin/devflow.js`
+- **Silent Failures** - Added error logging to `bin/devflow-install.js`
+- **Regex Bug** - Fixed `.match()` to `.test()` in `bin/devflow-install.js:30`
+- **Empty List Crash** - Added guard for empty list in `memory_summarize.py:138`
+- **Emoji Policy Violation** - Removed emojis from `CONTRIBUTING.md` table
+- **README Examples** - Updated deprecated `./run-story.sh` to `npx @pjmendonca/devflow story`
+- **SECURITY Agent** - Removed references to non-existent SECURITY agent from README
+
+### Changed
+- **DOC-STANDARD.md** - Renamed from "Stronger Project" to "Devflow"
+- **DOC-STANDARD.md** - Updated callout conventions to use text-based format (no emojis)
+- **REVIEWER Agent** - Fixed contradictory "rubber stamping" rule
+- **Agent Command** - Added missing `writer` to available agents list
+- **.gitignore** - Added `.claude/plans/` exclusion
+
 ## [1.13.2] - 2025-12-27
 
 ### Removed

package/README.md

@@ -9,6 +9,8 @@
 
 A production-ready, portable workflow automation system that uses Claude Code CLI to implement user stories with minimal human intervention. Think "CI/CD for development" - but instead of deploying code, it writes code.
 
+Find us at our [discord](https://discord.gg/mHdyQ7VN8R)
+
 ### Key Features
 
 - **Multi-Persona Agent System** - 8 specialized AI agents (SM, DEV, BA, ARCHITECT, PM, WRITER, MAINTAINER, REVIEWER)
@@ -23,6 +25,8 @@ A production-ready, portable workflow automation system that uses Claude Code CL
 - **Shared Memory** - Cross-agent memory pool for context sharing and learnings
 - **Agent Handoff System** - Structured context preservation between agent transitions
 - **Multi-Currency Cost Tracking** - Customizable currency display with budget controls and alerts
+- **Persistent Status Line** - Real-time context and cost percentage display in CLI
+- **Validation Framework** - Three-tier automated validation with auto-fix capability
 - **Project Agnostic** - Works with Flutter, Node.js, Python, Rust, Go, Ruby, etc.
 - **Guided Setup** - Interactive wizard guides you through installation
 
@@ -275,16 +279,16 @@ Multiple agents work together, debating and iterating until consensus:
 
 ```bash
 # Run swarm with default agents (ARCHITECT, DEV, REVIEWER)
-./run-story.sh 3-5 --swarm
+npx @pjmendonca/devflow story 3-5 --swarm
 
 # Custom agent selection
-./run-story.sh 3-5 --swarm --agents ARCHITECT,DEV,REVIEWER,SECURITY
+npx @pjmendonca/devflow story 3-5 --swarm --agents ARCHITECT,DEV,REVIEWER
 
 # Control iterations
-./run-story.sh 3-5 --swarm --max-iter 5
+npx @pjmendonca/devflow story 3-5 --swarm --max-iter 5
 
 # Set budget limits
-./run-story.sh 3-5 --swarm --budget 20.00
+npx @pjmendonca/devflow story 3-5 --swarm --budget 20.00
 ```
 
 **Swarm Configuration Options:**
@@ -313,7 +317,7 @@ Multiple agents work together, debating and iterating until consensus:
 DEV and REVIEWER work together in real-time:
 
 ```bash
-./run-story.sh 3-5 --pair
+npx @pjmendonca/devflow story 3-5 --pair
 ```
 
 **How it works:**
@@ -328,16 +332,16 @@ Let Devflow automatically select the best agents:
 
 ```bash
 # Auto-detect task type and select appropriate agents
-./run-story.sh "fix authentication bug" --auto-route
+npx @pjmendonca/devflow story "fix authentication bug" --auto-route
 
 # Works with any task description
-./run-story.sh "add user profile feature" --auto-route
+npx @pjmendonca/devflow story "add user profile feature" --auto-route
 ```
 
 **How it works:**
 - Analyzes task description for keywords
 - Considers file types and complexity
-- Routes to appropriate specialists (e.g., security -> SECURITY agent)
+- Routes to appropriate specialists (e.g., bugs -> MAINTAINER agent, new features -> DEV agent)
 
 ## Cost Tracking & Currency Configuration
 
@@ -434,6 +438,199 @@ python tooling/scripts/cost_dashboard.py --summary
 - **Set budget limits** - Prevent runaway costs with phase-specific limits
 - **Monitor the dashboard** - Track spending patterns across stories
 
+### Status Line
+
+Devflow provides a persistent status line in Claude Code that shows real-time metrics:
+
+```
+[Devflow] Claude Opus 4.5 | Context: 12.3% | Cost: $0.1234 (8.2%) | +45 -12 lines
+```
+
+**What it shows:**
+- **Model** - Current Claude model in use
+- **Context** - Percentage of context window used (with color coding)
+- **Cost** - Cumulative cost with subscription usage percentage
+- **Lines** - Lines added/removed in the session
+
+**Retroactive Cost Tracking:**
+
+The cost percentage is calculated retroactively across all sessions in your billing period:
+- Reads all session files from `tooling/.automation/costs/sessions/`
+- Sums tokens used within the billing period (default: 30 days)
+- Shows percentage of your subscription token limit used
+- Updates in real-time as you work
+
+**Color coding for cost percentage:**
+- **Green** - Under 75% of subscription limit
+- **Yellow** - 75-89% of subscription limit (warning)
+- **Red** - 90%+ of subscription limit (critical)
+
+**Configuration:**
+
+The status line reads currency settings from `tooling/.automation/costs/config.json`. To customize:
+
+```bash
+# Set display currency
+export COST_DISPLAY_CURRENCY="EUR"
+
+# Or edit config.json:
+{
+  "display_currency": "BRL",
+  "currency_rates": {
+    "USD": 1.0,
+    "BRL": 6.10,
+    "EUR": 0.92
+  }
+}
+```
+
+### Subscription Usage Tracking
+
+Track your usage against API subscription limits:
+
+```bash
+# View subscription usage
+python tooling/scripts/cost_dashboard.py --subscription
+
+# Set your plan manually
+python tooling/scripts/cost_dashboard.py --set-plan pro
+
+# View usage projection
+python tooling/scripts/cost_dashboard.py --subscription
+```
+
+**Auto-Detection:**
+
+Devflow automatically detects your subscription plan based on the model you're using:
+- **Opus** users -> Pro plan (5M tokens/month)
+- **Sonnet** users -> Developer plan (1M tokens/month)
+- **Haiku** users -> Free plan (100K tokens/month)
+
+The detected plan is saved to `tooling/.automation/costs/config.json` for future sessions.
+
+**Available plans:** free, developer, pro, scale, enterprise
+
+**Manual configuration (overrides auto-detection):**
+```bash
+export SUBSCRIPTION_PLAN="pro"           # Use a preset plan
+export SUBSCRIPTION_TOKEN_LIMIT=5000000  # Or set custom limit
+```
+
+### Model Efficiency Metrics
+
+Analyze which models give you the best value:
+
+```bash
+python tooling/scripts/cost_dashboard.py --efficiency
+```
+
+Shows cost-per-output-token for each model, helping optimize model selection.
+
+### Usage Projection & Forecasting
+
+Predict when you'll reach your subscription limits:
+
+```bash
+# View usage projection in subscription view
+python tooling/scripts/cost_dashboard.py --subscription
+```
+
+**What it shows:**
+- Daily average token consumption
+- Projected days until limit reached
+- End-of-period usage forecast vs limit
+- Color-coded status: on-track (green), warning (yellow), critical (red)
+
+### Analytics Export System
+
+Generate comprehensive analytics reports:
+
+```bash
+# Generate full analytics report (Markdown)
+python tooling/scripts/cost_dashboard.py --schedule-export report.md
+
+# Export to JSON format
+python tooling/scripts/cost_dashboard.py --schedule-export report.json
+```
+
+**Report contents:**
+- Daily usage trends (last 14 days with tokens, cost, sessions)
+- Per-story cost rankings (top 10 by token consumption)
+- Period comparison (current vs previous period with deltas)
+- API rate statistics (calls/day, calls/hour, peak times)
+
+### API Rate Tracking
+
+Monitor your API call patterns:
+
+```bash
+python tooling/scripts/cost_dashboard.py --summary
+```
+
+**Metrics tracked:**
+- Total API calls in period
+- Average calls per day/hour
+- Peak usage hour and day
+- Hourly and daily distribution data
+
+## Validation Framework
+
+Devflow includes a three-tier validation system that ensures code quality throughout the development pipeline.
+
+### Validation Tiers
+
+| Tier | Name | When | Validates |
+|------|------|------|-----------|
+| 1 | Pre-flight | Before starting | Story exists, budget available, dependencies |
+| 2 | Inter-phase | Between phases | Code compiles, lint passes, phase transitions |
+| 3 | Post-completion | After finishing | Tests pass, types valid, version synced |
+
+### Running Validation
+
+```bash
+# Validate a story
+/validate 3-5
+
+# Run specific tier
+/validate 3-5 --tier pre-flight
+
+# Run with auto-fix for lint issues
+/validate 3-5 --auto-fix
+```
+
+### Validation Gates
+
+**Pre-flight (Tier 1):**
+- Story file exists
+- Budget is available
+- Required dependencies installed
+
+**Inter-phase (Tier 2):**
+- TypeScript/Python compilation
+- Linting (with auto-fix option)
+- Phase transition rules
+
+**Post-completion (Tier 3):**
+- Test suite passes
+- Type checking passes
+- Version sync validated
+
+### Configuration
+
+Customize validation in `tooling/.automation/validation-config.yaml`:
+
+```yaml
+gates:
+  lint:
+    enabled: true
+    auto_fix: true
+    timeout: 60
+  test:
+    enabled: true
+    command: "npm test"
+    timeout: 300
+```
+
 ## Shell Completion
 
 Enable tab-completion for faster command entry.
@@ -550,7 +747,7 @@ Free to use in commercial and personal projects.
 
 
 <!-- VERSION_START - Auto-updated by update_version.py -->
-**Version**: 1.13.2
+**Version**: 1.19.0
 **Status**: Production Ready
-**Last Updated**: 2025-12-27
+**Last Updated**: 2026-01-03
 <!-- VERSION_END -->

package/bin/devflow-install.js

@@ -14,6 +14,7 @@ if (fs.existsSync(path.join(targetDir, '.claude', 'commands', 'story.md'))) {
   try {
     execSync(`node "${path.join(__dirname, 'devflow-validate.js')}"`, { stdio: 'inherit' });
   } catch (error) {
+    console.error('Validation failed. Please check the errors above.');
     process.exit(1);
   }
   process.exit(0);
@@ -27,7 +28,7 @@ function copyDir(src, dest, exclude = []) {
     const srcPath = path.join(src, entry.name);
     const destPath = path.join(dest, entry.name);
 
-    if (exclude.some(pattern => entry.name.match(pattern))) continue;
+    if (exclude.some(pattern => pattern.test(entry.name))) continue;
 
     if (entry.isDirectory()) {
       copyDir(srcPath, destPath, exclude);

package/bin/devflow.js

@@ -46,6 +46,10 @@ const command = args[0];
 if (commands[command]) {
   const binPath = require.resolve(`./devflow-${command}.js`);
   const child = spawn('node', [binPath, ...args.slice(1)], { stdio: 'inherit' });
+  child.on('error', (err) => {
+    console.error(`Failed to execute command: ${err.message}`);
+    process.exit(1);
+  });
   child.on('exit', (code) => process.exit(code || 0));
 } else {
   console.error(`Unknown command: ${command}`);