@howlil/ez-agents 3.4.2 → 3.5.0

package/ez-agents/bin/lib/url-fetch.cjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+
+/**
+ * URL Fetch Service
+ *
+ * Provides secure URL fetching with HTTPS validation and user confirmation.
+ * Only HTTPS URLs are allowed. HTTP, file, data, javascript, and vbscript protocols are blocked.
+ */
+
+const { URL } = require('url');
+const { URLFetchError } = require('./context-errors.cjs');
+
+const DEFAULT_TIMEOUT = 30000; // 30 seconds
+const BLOCKED_PROTOCOLS = ['http:', 'file:', 'data:', 'javascript:', 'vbscript:'];
+
+class URLValidator {
+  /**
+   * Validate a URL string
+   * @param {string} urlString - The URL to validate
+   * @returns {{valid: boolean, error?: string}} - Validation result
+   */
+  static validate(urlString) {
+    if (!urlString || typeof urlString !== 'string') {
+      return { valid: false, error: 'URL is required' };
+    }
+
+    try {
+      const url = new URL(urlString);
+
+      // Check protocol
+      if (url.protocol !== 'https:') {
+        if (BLOCKED_PROTOCOLS.includes(url.protocol)) {
+          return { 
+            valid: false, 
+            error: `Protocol '${url.protocol}' is not allowed. Only HTTPS is permitted.` 
+          };
+        }
+        return { 
+          valid: false, 
+          error: `Invalid protocol '${url.protocol}'. Only HTTPS is allowed.` 
+        };
+      }
+
+      // Check hostname exists
+      if (!url.hostname || url.hostname.trim() === '') {
+        return { valid: false, error: 'Invalid URL: missing hostname' };
+      }
+
+      // Reject localhost URLs
+      if (url.hostname === 'localhost' || 
+          url.hostname === '127.0.0.1' || 
+          url.hostname === '::1' ||
+          url.hostname.endsWith('.localhost')) {
+        return { 
+          valid: false, 
+          error: 'Localhost URLs are not allowed. Use a publicly accessible HTTPS URL.' 
+        };
+      }
+
+      return { valid: true };
+    } catch (err) {
+      return { 
+        valid: false, 
+        error: `Invalid URL format: ${err.message}` 
+      };
+    }
+  }
+}
+
+class URLFetchService {
+  /**
+   * Create a new URLFetchService instance
+   * @param {number} timeout - Request timeout in milliseconds (default: 30000)
+   */
+  constructor(timeout = DEFAULT_TIMEOUT) {
+    this.timeout = timeout;
+  }
+
+  /**
+   * Validate a URL
+   * @param {string} urlString - The URL to validate
+   * @returns {{valid: boolean, error?: string}} - Validation result
+   */
+  validateUrl(urlString) {
+    return URLValidator.validate(urlString);
+  }
+
+  /**
+   * Fetch content from a URL
+   * @param {string} url - The URL to fetch
+   * @returns {{content: string, contentType: string}} - Fetched content
+   * @throws {URLFetchError} - On fetch errors
+   */
+  async fetchUrl(url) {
+    // Validate URL first
+    const validation = this.validateUrl(url);
+    if (!validation.valid) {
+      throw new URLFetchError(url, validation.error);
+    }
+
+    try {
+      // Create abort controller for timeout
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+      const response = await fetch(url, {
+        headers: {
+          'User-Agent': 'ez-agents/1.0'
+        },
+        signal: controller.signal,
+        redirect: 'follow'
+      });
+
+      clearTimeout(timeoutId);
+
+      // Check for HTTP errors
+      if (!response.ok) {
+        throw new URLFetchError(
+          url, 
+          `HTTP ${response.status}: ${response.statusText}`
+        );
+      }
+
+      // Get content type
+      const contentType = response.headers.get('content-type') || 'text/plain';
+
+      // Get content
+      const content = await response.text();
+
+      return {
+        content,
+        contentType
+      };
+    } catch (err) {
+      if (err.name === 'AbortError') {
+        throw new URLFetchError(url, `Request timeout after ${this.timeout}ms`);
+      }
+      
+      if (err.name === 'URLFetchError') {
+        throw err;
+      }
+
+      throw new URLFetchError(url, `Network error: ${err.message}`);
+    }
+  }
+
+  /**
+   * Prompt user for confirmation before fetching a URL
+   * @param {string} url - The URL to fetch
+   * @returns {Promise<boolean>} - True if user confirmed
+   */
+  static async confirmUrlFetch(url) {
+    const readline = require('readline');
+    
+    return new Promise((resolve) => {
+      const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+      });
+
+      rl.question(`Fetch ${url}? (y/n): `, (answer) => {
+        rl.close();
+        resolve(answer.toLowerCase() === 'y');
+      });
+    });
+  }
+}
+
+module.exports = URLFetchService;
+module.exports.URLValidator = URLValidator;

package/ez-agents/references/metrics-schema.md

@@ -0,0 +1,118 @@
+# Metrics Schema Reference
+
+Schema for `.planning/metrics.json` — the EZ Agents success metrics store.
+
+## Full Schema
+
+```json
+{
+  "schema_version": "1.0",
+  "project": "project-name",
+  "updated": "2026-03-19T00:00:00Z",
+
+  "phase_metrics": [
+    {
+      "phase": 18,
+      "phase_name": "session-memory",
+      "plans_total": 4,
+      "plans_completed": 4,
+      "velocity_min": 24,
+      "defect_density": 0.12,
+      "bdd_pass_rate": 0.84,
+      "bdd_must_passing": 8,
+      "bdd_must_total": 9,
+      "deviation_count": 2,
+      "completed_at": "2026-03-19T00:00:00Z"
+    }
+  ],
+
+  "project_metrics": {
+    "requirements_coverage_pct": 78,
+    "test_coverage_pct": 74,
+    "bdd_scenarios_total": 60,
+    "bdd_scenarios_passing": 45,
+    "bdd_scenarios_must": 25,
+    "bdd_scenarios_must_passing": 24
+  },
+
+  "agent_metrics": {
+    "total_token_cost_usd": 18.40,
+    "avg_cost_per_plan": 0.27,
+    "deviation_rate": 0.15,
+    "avg_plans_per_phase": 3.2,
+    "avg_velocity_min_per_plan": 22
+  },
+
+  "business_metrics": {
+    "time_to_first_ship_days": 95,
+    "hotfixes_deployed": 0,
+    "milestones_shipped": 1,
+    "current_tier": "medium",
+    "phases_total": 29,
+    "phases_completed": 18
+  }
+}
+```
+
+## Field Definitions
+
+### phase_metrics[]
+
+| Field | Type | Source | Description |
+|-------|------|--------|-------------|
+| `phase` | int | ez-executor | Phase number |
+| `plans_total` | int | ez-executor | Plans in phase |
+| `plans_completed` | int | ez-executor | Plans with SUMMARY.md |
+| `velocity_min` | int | ez-executor | Minutes from first to last commit in phase |
+| `defect_density` | float | ez-executor | Deviations / tasks executed |
+| `bdd_pass_rate` | float | ez-verifier | @must scenarios passing / total @must |
+| `deviation_count` | int | ez-executor | Auto-fix deviations logged |
+
+### project_metrics
+
+| Field | Type | Source | Description |
+|-------|------|--------|-------------|
+| `requirements_coverage_pct` | int | ez-executor | % of REQUIREMENTS.md checked off |
+| `test_coverage_pct` | int | ez-verifier | From coverage tool output |
+| `bdd_scenarios_passing` | int | ez-verifier | Scenarios with green status |
+
+### agent_metrics
+
+| Field | Type | Source | Description |
+|-------|------|--------|-------------|
+| `total_token_cost_usd` | float | metrics-tracker | Accumulated from state.record-metric |
+| `avg_cost_per_plan` | float | metrics-tracker | total / plans_completed |
+| `deviation_rate` | float | metrics-tracker | total_deviations / total_tasks |
+
+### business_metrics
+
+| Field | Type | Source | Description |
+|-------|------|--------|-------------|
+| `time_to_first_ship_days` | int | ez-release-agent | Days from project init to first release |
+| `hotfixes_deployed` | int | ez-release-agent | Hotfixes tagged and pushed |
+| `current_tier` | string | tier-manager | mvp / medium / enterprise |
+
+## Capture Points
+
+| Metric | When Captured | Who Captures |
+|--------|---------------|--------------|
+| velocity_min | After SUMMARY.md created | ez-executor (state record-metric) |
+| deviation_count | During execution | ez-executor (per deviation Rule 1-3) |
+| defect_density | After plan completes | ez-executor (computed) |
+| bdd_pass_rate | After VERIFICATION.md | ez-verifier (metrics record-bdd) |
+| test_coverage_pct | After verification | ez-verifier (from coverage tool) |
+| requirements_coverage_pct | After mark-complete | ez-executor (computed from REQUIREMENTS.md) |
+| total_token_cost_usd | Ongoing | ez-executor (from state.record-metric cost field) |
+| hotfixes_deployed | After hotfix tag | ez-release-agent |
+
+## Dashboard Output
+
+```
+/ez:stats  →  enhanced dashboard
+
+PROGRESS:  Phase 18/29 (62%) | Requirements 78% | BDD 80%
+VELOCITY:  22 min/plan avg | Trend: ↑ IMPROVING
+QUALITY:   Coverage 74% | Defect density 0.12 | Deviation 15%
+COSTS:     $18.40 total | $0.27/plan | Est. remaining: ~$3.00
+RELEASE:   Tier: Medium | Hotfixes: 0 | Blockers: 0
+```

package/ez-agents/references/planning-config.md

@@ -197,4 +197,144 @@ Squash merge is recommended — keeps main branch history clean while preserving
 
 </branching_strategy_behavior>
 
+
+<smart_orchestration_config>
+
+**`smart_orchestration` block:**
+
+```json
+"smart_orchestration": {
+  "enabled": true,
+  "show_auto_prefix": true,
+  "auto_invoke": {
+    "preflight": ["progress", "execute-phase"],
+    "arch_review": ["execute-phase"],
+    "standup": []
+  }
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `enabled` | `true` | Master toggle for smart orchestration auto-invocations |
+| `show_auto_prefix` | `true` | Prefix auto-invoked agent output with `[AUTO]` label |
+| `auto_invoke.preflight` | `["progress", "execute-phase"]` | Commands that silently run health check before executing |
+| `auto_invoke.arch_review` | `["execute-phase"]` | Commands that auto-spawn tech lead review when `agent_discussion` enabled |
+| `auto_invoke.standup` | `[]` | Commands that auto-generate standup before running |
+
+**Disabling per-invocation:** Pass `--no-auto` flag to any command to skip smart orchestration for that run.
+
+</smart_orchestration_config>
+
+<agent_discussion_config>
+
+**`agent_discussion` block:**
+
+```json
+"agent_discussion": {
+  "enabled": false,
+  "pre_flight_observer": false,
+  "tech_lead_review": false,
+  "scrum_master_standup": false,
+  "cost_warning": true
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `enabled` | `false` | Master toggle for optional discussion agents |
+| `pre_flight_observer` | `false` | Spawn observer agent before execution to surface risks |
+| `tech_lead_review` | `false` | Auto-spawn tech lead review after `/ez:plan-phase` completes |
+| `scrum_master_standup` | `false` | Auto-generate standup report at session start |
+| `cost_warning` | `true` | Warn before spawning expensive agents (Opus-class) |
+
+**Enable via `/ez:settings`:** The settings workflow provides a guided UI for toggling these options. Avoid manual JSON edits.
+
+</agent_discussion_config>
+
+<sessions_config>
+
+**`sessions` block:**
+
+```json
+"sessions": {
+  "retention_policy": "keep_last_10",
+  "auto_compress_threshold": 50,
+  "chain_navigation_enabled": true
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `retention_policy` | `"keep_last_10"` | How many sessions to retain. Options: `"keep_all"`, `"keep_last_N"`, `"keep_days_N"` |
+| `auto_compress_threshold` | `50` | Compress session memory when token count exceeds this (in thousands) |
+| `chain_navigation_enabled` | `true` | Enable `--previous`/`--next`/`--chain` flags in `/ez:resume` |
+
+**Session files location:** `.planning/sessions/` — each session is a JSON file. Use `/ez:export-session` and `/ez:import-session` for cross-model handoffs.
+
+</sessions_config>
+
+<release_tiers_config>
+
+**`release.tiers` block:**
+
+```json
+"release": {
+  "tier": "mvp",
+  "tiers": {
+    "mvp": {
+      "coverage_threshold": 0,
+      "checklist_items": ["build_passes", "no_blockers"],
+      "git_strategy": "direct_to_main"
+    },
+    "medium": {
+      "coverage_threshold": 60,
+      "checklist_items": ["build_passes", "no_blockers", "tests_pass", "security_scan"],
+      "git_strategy": "pr_required"
+    },
+    "enterprise": {
+      "coverage_threshold": 80,
+      "checklist_items": ["build_passes", "no_blockers", "tests_pass", "security_scan", "coverage_gate", "changelog_updated", "rollback_plan"],
+      "git_strategy": "gitflow"
+    }
+  }
+}
+```
+
+| Tier | Coverage | Git Strategy | Checklist |
+|------|----------|--------------|-----------|
+| `mvp` | None | Direct to main | Build + no blockers |
+| `medium` | 60% | PR required | Build + tests + security scan |
+| `enterprise` | 80% | GitFlow (main + develop) | Full gates including rollback plan |
+
+**Hotfix behavior by tier:** MVP hotfixes merge directly; Medium requires PR; Enterprise merges to main AND syncs to develop. See `/ez:hotfix` documentation.
+
+**Set tier:** `node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" config-set release.tier enterprise`
+
+</release_tiers_config>
+
+<package_manager_config>
+
+**`packageManager` block:**
+
+```json
+"packageManager": {
+  "default": "npm",
+  "autoDetect": true,
+  "respectLockfile": true
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `default` | `"npm"` | Fallback package manager when auto-detection fails. Options: `"npm"`, `"yarn"`, `"pnpm"`, `"bun"` |
+| `autoDetect` | `true` | Detect package manager from lock file presence (`yarn.lock`, `pnpm-lock.yaml`, `bun.lockb`) |
+| `respectLockfile` | `true` | Use `--frozen-lockfile` / `--ci` flags during install to prevent lock file mutations |
+
+**Auto-detection order:** `bun.lockb` → bun, `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `package-lock.json` → npm, fallback to `default`.
+
+**Set explicitly:** `node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" config-set packageManager.default pnpm`
+
+</package_manager_config>
+
 </planning_config>

package/ez-agents/references/tier-strategy.md

@@ -0,0 +1,103 @@
+# Tier Strategy Reference
+
+Decision reference for git branching and release strategy per tier.
+
+## Quick Decision Matrix
+
+| Question | MVP | Medium | Enterprise |
+|----------|-----|--------|------------|
+| Git strategy | Trunk (tag main) | GitHub Flow | GitFlow |
+| Release branch | None | `release/vX.Y.Z` | `release/vX.Y.Z` from develop |
+| Hotfix to develop? | No | No | Yes |
+| PR required? | No | Yes (optional) | Yes (required) |
+| Coverage gate | 60% | 80% | 95% |
+| Checklist items | 6 | 18 | 30 |
+| MoSCoW scope | @must | @must + @should | All |
+| Rollback window | 30 min | 15 min | 5 min |
+
+## When to Use Each Tier
+
+**MVP** — You need to ship NOW
+- First public release
+- Early access / beta
+- Founder-driven sales demo
+- Internal tool, no SLA
+
+**Medium** — Real users, real consequences
+- General availability
+- Paying customers
+- Public-facing product
+- Team of 2-10 developers
+
+**Enterprise** — Compliance matters
+- Fortune 500 customers
+- Regulated industry (finance, health, legal)
+- SOC2 / GDPR required
+- 24/7 SLA commitment
+
+## Tier Promotion Path
+
+```
+Initial release → MVP v1.0.0
+  ↓ (enough users to need reliability)
+GA release → Medium v1.5.0
+  ↓ (enterprise deal signed)
+Enterprise → v2.0.0
+```
+
+Each promotion is additive — enterprise features are behind feature flags in the codebase from day one. Promotion just enables the flags and runs the stricter checklist.
+
+## Feature Flag Convention
+
+```javascript
+// In code: guard enterprise/medium features
+const ENABLE_SHOULD_FEATURES = process.env.ENABLE_SHOULD_FEATURES === 'true';
+const ENABLE_COULD_FEATURES = process.env.ENABLE_COULD_FEATURES === 'true';
+
+// MVP deploy: both = false (no overhead)
+// Medium deploy: SHOULD = true
+// Enterprise: SHOULD = true, COULD = true
+```
+
+## GitFlow (Enterprise) Branch Layout
+
+```
+main          ← production releases (tagged)
+develop       ← integration branch
+  feature/*   ← new features
+  fix/*        ← bug fixes
+release/vX.Y.Z ← release preparation (from develop → main)
+hotfix/*      ← emergency production fixes (from main → main + develop)
+```
+
+## GitHub Flow (Medium) Branch Layout
+
+```
+main          ← production (deploy on merge)
+  feature/*   ← all work branches
+  release/vX.Y.Z ← optional: release prep branch
+  hotfix/*    ← emergency fixes
+```
+
+## Trunk-Based (MVP) Branch Layout
+
+```
+main          ← production + development
+  task/*      ← short-lived feature branches (optional)
+              ← hotfix directly if needed
+```
+
+## Config Location
+
+Tier is stored in `.planning/config.json`:
+
+```json
+{
+  "release": {
+    "tier": "mvp",
+    "tiers": { ... }
+  }
+}
+```
+
+Update with: `node ez-tools.cjs tier-manager save-tier medium`

package/ez-agents/templates/bdd-feature.md

@@ -0,0 +1,173 @@
+# BDD Feature File Template
+
+Use this template when creating `.feature` files for a phase.
+
+Replace `{placeholders}` with actual content.
+
+---
+
+```gherkin
+# specs/features/{domain}/{feature-name}.feature
+#
+# Feature: {feature-name}
+# Phase: {phase-number} — {phase-name}
+# MoSCoW: @must | @should | @could | @wont
+# Tier: @mvp | @medium | @enterprise
+#
+# Requirements: {REQ-IDs this feature satisfies}
+
+Feature: {Feature Name}
+  As a {user role}
+  I want to {action/capability}
+  So that {benefit/value delivered}
+
+  # Background sets up shared preconditions for all scenarios in this Feature.
+  # Remove if no shared setup needed.
+  Background:
+    Given {shared precondition 1}
+    And {shared precondition 2}
+
+  # ─────────────────────────────────────────────
+  # MUST — Required for MVP (phase gate)
+  # ─────────────────────────────────────────────
+
+  @must @mvp
+  Scenario: {Happy path — primary success case}
+    Given {initial context / system state}
+    When {user performs action}
+    Then {expected outcome}
+    And {additional assertion}
+
+  @must @mvp
+  Scenario: {Primary error case}
+    Given {initial context}
+    When {user performs invalid action}
+    Then {expected error response}
+    And {system remains in valid state}
+
+  # ─────────────────────────────────────────────
+  # SHOULD — Target for medium tier release
+  # ─────────────────────────────────────────────
+
+  @should @medium
+  Scenario: {Secondary success case or edge case}
+    Given {context}
+    When {action}
+    Then {outcome}
+
+  @should @medium
+  Scenario: {Error recovery or retry flow}
+    Given {context where partial failure occurred}
+    When {user attempts recovery}
+    Then {system handles gracefully}
+
+  # ─────────────────────────────────────────────
+  # COULD — Nice-to-have for enterprise tier
+  # ─────────────────────────────────────────────
+
+  @could @enterprise
+  Scenario: {Advanced or compliance feature}
+    Given {enterprise context}
+    When {action}
+    Then {enterprise-specific outcome}
+
+  # ─────────────────────────────────────────────
+  # WONT — Explicitly deferred (document reasons)
+  # ─────────────────────────────────────────────
+  # @wont — SSO integration: deferred to Phase XX, depends on identity provider decision
+  # @wont — Biometric auth: deferred — mobile-only feature, out of scope for web
+```
+
+---
+
+## Scenario Writing Guide
+
+### Given (Precondition)
+Sets up the world before the action. Should be:
+- Specific: "Given a user exists with email test@example.com" not "Given a user exists"
+- Minimal: Only include context relevant to this scenario
+- Reusable: Use Background for context shared by all scenarios
+
+```gherkin
+# Good
+Given a registered user with email "alice@example.com" exists
+And the user's account is in "active" status
+
+# Bad (too vague)
+Given there is a user
+```
+
+### When (Action)
+The single event being tested. Rules:
+- One action per scenario (split if multiple)
+- Active voice: "When I submit the form" not "When the form is submitted"
+- From user's perspective
+
+```gherkin
+# Good
+When I submit the login form with email "alice@example.com" and password "secret123"
+
+# Bad (multiple actions)
+When I fill in the form and click submit and wait for response
+```
+
+### Then (Outcome)
+Observable, verifiable result. Must be:
+- Testable: Can be automated
+- Specific: Exact values, not "something happens"
+- From user's perspective
+
+```gherkin
+# Good
+Then I am redirected to "/dashboard"
+And the page title contains "Welcome, Alice"
+And a session cookie named "ez_session" is present
+
+# Bad (subjective)
+Then it works correctly
+And the user is happy
+```
+
+### And / But
+- `And` — continues the clause type (Given+And, When+And, Then+And)
+- `But` — negative assertion ("But I should not see...")
+
+---
+
+## MoSCoW Quick Reference
+
+| Tag | When to Use | Tier |
+|-----|-------------|------|
+| `@must` | System is broken/unusable without it | `@mvp` |
+| `@should` | Important but workaround exists | `@medium` |
+| `@could` | Enhances experience but not critical | `@enterprise` |
+| `@wont` | Explicitly out of scope (document why) | — |
+
+---
+
+## File Naming Convention
+
+```
+specs/
+  features/
+    {domain}/
+      {feature-name}.feature    # e.g., auth/login.feature
+      {feature-name}.feature    # e.g., auth/registration.feature
+    {domain2}/
+      {feature-name}.feature
+```
+
+Domain examples: `auth`, `payments`, `dashboard`, `onboarding`, `settings`, `api`
+
+---
+
+## INVEST Checklist
+
+Before finalizing a Feature, verify all scenarios as a group:
+
+- [ ] **Independent**: Feature can be developed without dependency on other features in this file
+- [ ] **Negotiable**: Implementation details (not described in Then) are flexible
+- [ ] **Valuable**: The Feature statement explains clear user value
+- [ ] **Estimable**: A developer can estimate effort from these scenarios
+- [ ] **Small**: All @must scenarios fit in one phase (split if more than ~8 must scenarios)
+- [ ] **Testable**: Every Then clause can be automated