antigravity-ai-kit 3.1.1 → 3.2.0

package/.agent/workflows/plan.md

@@ -1,9 +1,9 @@
 ---
 description: Create implementation plan. Invokes planner agent for structured task breakdown.
-version: 2.1.0
+version: 2.2.0
 sdlc-phase: plan
 agents: [planner]
-skills: [plan-writing, brainstorming]
+skills: [plan-writing, brainstorming, plan-validation]
 commit-types: [docs]
 ---
 
@@ -55,14 +55,33 @@ commit-types: [docs]
    - Note dependencies and integration points
 
 3. **Create Plan**
-   - Break down the task into small, focused steps
+   - The loading engine provides `matchedDomains` and `mandatoryRules` — pass these to the planner agent
+   - Consult all mandatory rules (security, testing, coding-style, documentation, git-workflow) using the Rule Extraction Algorithm
+   - Classify task size: Trivial (1-2 files), Medium (3-10 files), Large (10+ files)
+   - Break down the task into right-sized steps with exact file paths (see plan-writing SKILL.md Principle 1)
    - Assign verification criteria to each step
    - Order tasks logically (dependencies first)
+   - Include cross-cutting concerns (security, testing, documentation) — ALWAYS, for ALL task sizes
+   - For Medium/Large tasks: invoke specialist synthesis (security-reviewer, tdd-guide, architect) per the Specialist Invocation Protocol
+   - Include domain-specific sections based on `matchedDomains` (see `domain-enhancers.md`)
    - Identify which agents are needed for multi-domain tasks
    - Save plan to `docs/PLAN-{task-slug}.md`
 
+// turbo
+3.5. **Validate Plan Quality**
+   - The planner performs self-validation using the `plan-validation` skill checklist:
+     1. Classify task size from file count and effort estimate
+     2. Schema compliance: verify all required Tier sections are present and populated
+     3. Cross-cutting verification: Security, Testing, Documentation sections are non-empty (or explicit "N/A — [reason]")
+     4. Specificity audit: every implementation step includes a file path
+     5. Score the plan against the rubric in `plan-schema.md`
+     6. Apply domain scoring: +2 bonus per matched domain with enhancer, -2 penalty per missing
+   - **Verdict**: Score >= 70% of tier max → PASS (present to user with score)
+   - **Revision**: Score < 70% → identify gaps, revise, re-validate (max 2 cycles, then present with warnings)
+   - The quality score is displayed alongside the plan for transparency
+
 4. **Present for Approval**
-   - Show the plan summary to the user
+   - Show the plan summary to the user with quality score
    - Wait for explicit approval before any implementation
 
 ---
@@ -122,20 +141,42 @@ Approve to start implementation with `/create` or `/enhance`.
 
 **REQUIRED:**
 - At least 3 clarifying questions before planning
+- Mandatory rule consultation before plan creation
 - Verification criteria for every task
+- Cross-cutting concerns (security, testing, documentation) in every plan
+- Plan validation against quality schema before presentation
 - User approval before implementation begins
 - Plan file saved in `docs/` with dynamic name
 
 ---
 
+## Post-Implementation Retrospective
+
+After the planned task is fully implemented and verified (reaches VERIFY phase), the `plan-complete` hook triggers a retrospective:
+
+1. **Trigger**: Workflow state transitions to VERIFY (or user runs `/retrospective` on a completed plan)
+2. **Data Source**: Compare `docs/PLAN-{slug}.md` against `git diff --name-only` from plan start
+3. **Execution**: Run the plan-retrospective protocol (`.agent/skills/plan-writing/plan-retrospective.md`)
+4. **Output**: Append one row to `.agent/contexts/plan-quality-log.md`
+5. **Feedback Loop**: Planner reads the quality log at planning time (Step 1, Requirements Analysis) to adjust estimates, predict surprise files, and weight risk categories
+
+This is non-blocking (severity: medium, onFailure: log). If skipped, no impact on current work, but future plan accuracy degrades.
+
+---
+
 ## Completion Criteria
 
 - [ ] Clarifying questions asked and answered
 - [ ] Codebase explored for relevant context
-- [ ] Plan created with verifiable tasks
+- [ ] Mandatory rules consulted (security, testing, coding-style, documentation)
+- [ ] Plan created with verifiable tasks and exact file paths
+- [ ] Cross-cutting concerns addressed (security, testing, documentation)
+- [ ] Plan validated against quality schema (score >= 70% of tier max)
+- [ ] Domain-specific sections included for all matched domains
 - [ ] Plan saved to `docs/PLAN-{slug}.md`
 - [ ] User has reviewed and approved the plan
 - [ ] After approval: proceed to `/create` or `/enhance` for implementation
+- [ ] After implementation: retrospective logged to `plan-quality-log.md` (via plan-complete hook)
 
 ---
 
@@ -144,4 +185,7 @@ Approve to start implementation with `/create` or `/enhance`.
 - **Previous**: `/brainstorm` (explore options) · `/quality-gate` (validate approach)
 - **Next**: `/create` (scaffold new features) · `/enhance` (iterative development)
 - **Skill**: `.agent/skills/plan-writing/SKILL.md`
+- **Schema**: `.agent/skills/plan-writing/plan-schema.md`
+- **Domains**: `.agent/skills/plan-writing/domain-enhancers.md`
+- **Validation**: `.agent/skills/plan-validation/SKILL.md`
 - **Agent**: `planner` agent (see `.agent/agents/planner.md`)

package/README.md

@@ -1,13 +1,13 @@
 # 🚀 Antigravity AI Kit
 
-![version](https://img.shields.io/badge/version-3.1.0-blue)
+![version](https://img.shields.io/badge/version-3.2.0-blue)
 ![license](https://img.shields.io/badge/license-MIT-green)
 ![AI Agents](https://img.shields.io/badge/AI%20Agents-19-purple)
-![Skills](https://img.shields.io/badge/Skills-31-orange)
+![Skills](https://img.shields.io/badge/Skills-32-orange)
 ![Commands](https://img.shields.io/badge/Commands-31-red)
 ![Workflows](https://img.shields.io/badge/Workflows-14-teal)
-![Runtime Modules](https://img.shields.io/badge/Runtime%20Modules-21-blueviolet)
-![Tests](https://img.shields.io/badge/Tests-261%20passing-brightgreen)
+![Runtime Modules](https://img.shields.io/badge/Runtime%20Modules-29-blueviolet)
+![Tests](https://img.shields.io/badge/Tests-327%20passing-brightgreen)
 ![Checklists](https://img.shields.io/badge/Checklists-3-yellow)
 
 <p align="center">
@@ -15,7 +15,7 @@
 </p>
 
 <p align="center">
-  Antigravity AI Kit is a <b>Trust-Grade AI development framework</b> with a <b>21-module runtime engine</b>, <b>19 specialized agents</b>, <b>31 commands</b>, <b>31 skills</b>, and <b>14 workflows</b> — all backed by <b>261 tests</b> and governance-first principles.
+  Antigravity AI Kit is a <b>Trust-Grade AI development framework</b> with a <b>29-module runtime engine</b>, <b>19 specialized agents</b>, <b>31 commands</b>, <b>32 skills</b>, and <b>14 workflows</b> — all backed by <b>327 tests</b> and governance-first principles.
 </p>
 
 <p align="center">
@@ -38,8 +38,8 @@
 - [Architecture](#%EF%B8%8F-architecture-overview)
 - [Agents](#-agents-19)
 - [Commands](#%EF%B8%8F-commands-31)
-- [Skills](#%EF%B8%8F-skills-31)
-- [Runtime Engine](#%EF%B8%8F-runtime-engine-21-modules)
+- [Skills](#%EF%B8%8F-skills-32)
+- [Runtime Engine](#%EF%B8%8F-runtime-engine-29-modules)
 - [Workflows](#-workflows-14)
 - [Operating Constraints](#%EF%B8%8F-operating-constraints)
 - [Session Management](#-session-management)
@@ -56,14 +56,14 @@
 | Feature           | Count | Description                                                            |
 | :---------------- | :---- | :--------------------------------------------------------------------- |
 | 🤖 **AI Agents**  | 19    | Specialized roles (Mobile, DevOps, Database, Security, Performance...) |
-| 🛠️ **Skills**     | 31    | Domain knowledge modules (API, Testing, MCP, Architecture, Docker...) |
+| 🛠️ **Skills**     | 32    | Domain knowledge modules (API, Testing, MCP, Architecture, Docker...) |
 | ⌨️ **Commands**   | 31    | Slash commands for every development workflow                          |
 | 🔄 **Workflows**  | 14    | Process templates (/create, /debug, /deploy, /test...)                 |
-| ⚙️ **Runtime**    | 21    | Runtime engine modules (governance, reputation, self-healing...)       |
+| ⚙️ **Runtime**    | 29    | Runtime engine modules (governance, reputation, self-healing...)       |
 | ✅ **Checklists** | 3     | Quality gates (session-start, session-end, pre-commit)                 |
 | ⚖️ **Rules**      | 8     | Modular governance constraints (coding, security, testing, git, docs, sprint)  |
-| 🔗 **Hooks**      | 6     | Event-driven automation (runtime + git-hook enforcement)               |
-| 🧪 **Tests**      | 261   | Unit, structural, and security tests (25 test files)                   |
+| 🔗 **Hooks**      | 7     | Event-driven automation (runtime + git-hook enforcement)               |
+| 🧪 **Tests**      | 327   | Unit, structural, integration, and security tests (32 test files)      |
 
 ---
 
@@ -71,7 +71,7 @@
 
 - **🔒 Trust-Grade Governance**: `/explore → /plan → /work → /review` — Each iteration builds context
 - **🤖 Multi-Agent System**: 19 specialized agents that collaborate (Mobile Developer, DevOps, Database Architect, Sprint Orchestrator...)
-- **⚙️ Runtime Engine**: 21 modules enforcing workflow transitions, task governance, agent reputation, self-healing, and marketplace
+- **⚙️ Runtime Engine**: 29 modules enforcing workflow transitions, task governance, agent reputation, self-healing, and marketplace
 - **📦 Context as Artifact**: Persistent markdown files for plans, specs, and decisions
 - **🔄 Continuous Learning**: PAAL cycle extracts patterns from every session
 - **🛡️ Security First**: Built-in secret detection, vulnerability scanning, and compliance checks
@@ -150,7 +150,7 @@ ag-kit scan       # Security scan
 │  │ TDD Specialist   │  │ DB, DevOps       │  │ Knowledge        │  │
 │  └────────┬─────────┘  └────────┬─────────┘  └────────┬─────────┘  │
 ├───────────┼─────────────────────┼─────────────────────┼────────────┤
-│           ▼              SKILL LAYER (31)              ▼            │
+│           ▼              SKILL LAYER (32)              ▼            │
 │  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  │
 │  │ Orchestration    │  │ Operational      │  │ Domain Skills    │  │
 │  │ Routing, Modes   │  │ Verification     │  │ API, Testing     │  │
@@ -160,10 +160,10 @@ ag-kit scan       # Security scan
 │           ▼           GOVERNANCE LAYER                 ▼            │
 │  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  │
 │  │ rules/ (8)       │  │ hooks.json       │  │ manifest.json    │  │
-│  │ Governance       │  │ 6 Event Hooks    │  │ Integrity Check  │  │
+│  │ Governance       │  │ 7 Event Hooks    │  │ Integrity Check  │  │
 │  └──────────────────┘  └──────────────────┘  └──────────────────┘  │
 ├─────────────────────────────────────────────────────────────────────┤
-│                    RUNTIME ENGINE (21 modules)                      │
+│                    RUNTIME ENGINE (29 modules)                      │
 │  workflow-engine · session-manager · task-governance                │
 │  agent-reputation · self-healing · marketplace · + 15 more         │
 └─────────────────────────────────────────────────────────────────────┘
@@ -186,7 +186,7 @@ EXPLORE → PLAN → IMPLEMENT → VERIFY → REVIEW → DEPLOY
 | **REVIEW** | Code review (human or Copilot) | Review approved |
 | **DEPLOY** | Production deployment | Deployment checklist complete |
 
-**Intelligent Routing**: The kit analyzes your request keywords and automatically loads the right agents and skills (max 4 agents + 6 skills per session to stay within context budgets).
+**Intelligent Routing**: The kit analyzes your request keywords (including implicit security triggers like "login", "payment", "upload") and automatically loads the right agents and skills (max 4 agents + 8 skills per session to stay within context budgets). Planning workflows use protected budget enforcement — mandatory skills survive trimming even when over budget.
 
 ---
 
@@ -226,7 +226,7 @@ EXPLORE → PLAN → IMPLEMENT → VERIFY → REVIEW → DEPLOY
 
 | Agent                    | Role                              | Triggers                      |
 | :----------------------- | :-------------------------------- | :---------------------------- |
-| **Planner**              | Task breakdown, Socratic analysis | plan, breakdown, requirements |
+| **Planner**              | Multi-agent plan synthesis, tiered quality schema, specialist coordination | plan, breakdown, requirements |
 | **Sprint Orchestrator**  | Sprint planning, velocity         | sprint, roadmap, velocity     |
 | **Reliability Engineer** | SRE, production readiness         | reliability, SLA, monitoring  |
 
@@ -302,7 +302,7 @@ EXPLORE → PLAN → IMPLEMENT → VERIFY → REVIEW → DEPLOY
 
 ---
 
-## 🛠️ Skills (31)
+## 🛠️ Skills (32)
 
 ### Operational Skills (5)
 
@@ -341,7 +341,7 @@ EXPLORE → PLAN → IMPLEMENT → VERIFY → REVIEW → DEPLOY
 | `git-workflow`         | Branching, commits              |
 | `i18n-localization`    | Internationalization patterns   |
 
-### Development Skills (9)
+### Development Skills (10)
 
 | Skill                   | Purpose                 |
 | :---------------------- | :---------------------- |
@@ -351,15 +351,16 @@ EXPLORE → PLAN → IMPLEMENT → VERIFY → REVIEW → DEPLOY
 | `deployment-procedures` | CI/CD, rollback         |
 | `performance-profiling` | Core Web Vitals         |
 | `brainstorming`         | Socratic discovery      |
-| `plan-writing`          | Structured planning     |
+| `plan-writing`          | Structured planning with tiered quality schema |
+| `plan-validation`       | Quality gate with completeness scoring |
 | `shell-conventions`     | PowerShell/Bash conventions |
 | `ui-ux-pro-max`         | Premium UI/UX design system |
 
 ---
 
-## ⚙️ Runtime Engine (21 Modules)
+## ⚙️ Runtime Engine (29 Modules)
 
-Antigravity AI Kit v3.1.0 includes a **full runtime engine** built across 4 phases — all using Node.js built-ins with zero external dependencies.
+Antigravity AI Kit v3.2.0 includes a **full runtime engine** built across 4 phases — all using Node.js built-ins with zero external dependencies.
 
 ### Phase 1 — Foundation Hardening
 
@@ -377,7 +378,7 @@ Antigravity AI Kit v3.1.0 includes a **full runtime engine** built across 4 phas
 |:---|:---|
 | `workflow-persistence` | Persistent state + checkpoints |
 | `agent-registry` | Agent contract validation |
-| `loading-engine` | Keyword matching + context budget |
+| `loading-engine` | Keyword matching + implicit triggers + context budget |
 | `hook-system` | Event-driven lifecycle hooks |
 | `task-model` | Task CRUD with status tracking |
 
@@ -614,16 +615,16 @@ antigravity-ai-kit/
 ├── .agent/                    # Core AI Kit
 │   ├── agents/               # 19 specialized agents
 │   ├── commands/             # 31 slash commands
-│   ├── skills/               # 31 capability modules
+│   ├── skills/               # 32 capability modules
 │   ├── workflows/            # 14 process templates
 │   ├── engine/               # Autonomy Engine (state machine, loading rules, configs)
-│   ├── hooks/                # 6 event hooks (runtime + git-hook)
+│   ├── hooks/                # 7 event hooks (runtime + git-hook)
 │   ├── rules/                # 8 modular governance rules
 │   ├── checklists/           # Verification checklists (3)
 │   ├── templates/            # ADR, feature-request, bug-report templates
 │   ├── decisions/            # Architecture Decision Records
 │   └── manifest.json         # Machine-readable capability registry
-├── lib/                       # Runtime Engine (21 modules)
+├── lib/                       # Runtime Engine (29 modules)
 │   ├── workflow-engine.js    # State machine enforcement
 │   ├── task-governance.js    # Locking, audit trail, decision timeline
 │   ├── agent-reputation.js   # Score tracking & rankings
@@ -632,8 +633,8 @@ antigravity-ai-kit/
 │   └── + 16 more modules     # Identity, plugins, hooks, registry...
 ├── bin/                       # CLI (ag-kit)
 ├── create-antigravity-app/    # Project scaffolder (separate npm package)
-├── tests/                     # Test suites (261 tests, 25 files)
-│   ├── unit/                 # 21 module tests
+├── tests/                     # Test suites (327 tests, 32 files)
+│   ├── unit/                 # Module tests (loading-engine, self-healing, plugins...)
 │   ├── structural/           # Inventory + schema validation
 │   └── security/             # Injection scan + leakage detection
 ├── docs/                      # MkDocs documentation site
@@ -710,7 +711,7 @@ Want to use Antigravity AI Kit in your project? The **[Contributor Guide](https:
 - Context-driven development from [Google Conductor](https://developers.googleblog.com/en/conductor-introducing-context-driven-development-for-gemini-cli/)
 - Hook concepts from [everything-claude-code](https://github.com/affaan-m/everything-claude-code)
 
-_Antigravity AI Kit v3.1.0 extends these foundations with a 21-module runtime engine, Trust-Grade governance, session management, and 100+ capabilities._
+_Antigravity AI Kit v3.2.0 extends these foundations with a 29-module runtime engine, Trust-Grade governance, session management, and 100+ capabilities._
 
 ---
 

package/bin/ag-kit.js

@@ -14,7 +14,7 @@
 const fs = require('fs');
 const path = require('path');
 
-const VERSION = '3.0.0';
+const VERSION = require('../package.json').version;
 const AGENT_FOLDER = '.agent';
 
 // ANSI colors
@@ -71,6 +71,7 @@ ${colors.bright}Usage:${colors.reset}
   ag-kit market info <name> Get marketplace plugin details
   ag-kit market install <n> Install from marketplace
   ag-kit heal [--file <f>]  Detect and diagnose CI failures
+  ag-kit health             Run aggregated health check
   ag-kit --help             Show this help message
   ag-kit --version          Show version
 
@@ -524,16 +525,28 @@ const options = {
   file: null,
 };
 
-// Parse --path option
+// Parse --path option with traversal protection (H-7: use path.resolve boundary check)
 const pathIndex = args.indexOf('--path');
 if (pathIndex !== -1 && args[pathIndex + 1]) {
-  options.path = args[pathIndex + 1];
+  const resolvedPath = path.resolve(args[pathIndex + 1]);
+  const cwd = process.cwd();
+  if (!resolvedPath.startsWith(cwd + path.sep) && resolvedPath !== cwd) {
+    log('Error: --path must resolve within current working directory', 'red');
+    process.exit(1);
+  }
+  options.path = resolvedPath;
 }
 
-// Parse --file option
+// Parse --file option with traversal protection (H-7: use path.resolve boundary check)
 const fileIndex = args.indexOf('--file');
 if (fileIndex !== -1 && args[fileIndex + 1]) {
-  options.file = args[fileIndex + 1];
+  const resolvedFile = path.resolve(args[fileIndex + 1]);
+  const cwdForFile = process.cwd();
+  if (!resolvedFile.startsWith(cwdForFile + path.sep) && resolvedFile !== cwdForFile) {
+    log('Error: --file must resolve within current working directory', 'red');
+    process.exit(1);
+  }
+  options.file = resolvedFile;
 }
 
 // Execute command
@@ -567,6 +580,14 @@ switch (command) {
     cliCmd.healCommand(process.cwd(), { file: options.file, apply: options.apply });
     break;
   }
+  case 'health': {
+    const cliHealth = require('../lib/cli-commands');
+    const result = cliHealth.healthCommand(process.cwd());
+    if (!result.healthy) {
+      process.exit(1);
+    }
+    break;
+  }
   case '--version':
   case '-v':
     console.log(VERSION);

package/lib/agent-registry.js

@@ -14,7 +14,7 @@
 const fs = require('fs');
 const path = require('path');
 
-const AGENT_DIR = '.agent';
+const { AGENT_DIR } = require('./constants');
 const AGENTS_SUBDIR = 'agents';
 const MANIFEST_FILE = 'manifest.json';
 
@@ -153,7 +153,14 @@ function validateAgent(agentName, projectRoot) {
  */
 function validateAllAgents(projectRoot) {
   const manifestPath = path.join(projectRoot, AGENT_DIR, MANIFEST_FILE);
-  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return { total: 0, valid: 0, invalid: 0, agents: [] };
+  }
+
   const agents = manifest.capabilities?.agents?.items || [];
 
   const results = agents.map((agent) => validateAgent(agent.name, projectRoot));
@@ -175,7 +182,14 @@ function validateAllAgents(projectRoot) {
  */
 function loadRegistry(projectRoot) {
   const manifestPath = path.join(projectRoot, AGENT_DIR, MANIFEST_FILE);
-  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return { agents: [], totalCount: 0 };
+  }
+
   const agents = manifest.capabilities?.agents?.items || [];
 
   return {

package/lib/agent-reputation.js

@@ -15,8 +15,8 @@ const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 
-const AGENT_DIR = '.agent';
-const ENGINE_DIR = 'engine';
+const { AGENT_DIR, ENGINE_DIR } = require('./constants');
+const { writeJsonAtomic } = require('./io');
 const REPUTATION_FILE = 'reputation.json';
 
 /** Score bounds */
@@ -95,15 +95,7 @@ function loadReputationData(projectRoot) {
  */
 function writeReputationData(projectRoot, data) {
   const filePath = resolveReputationPath(projectRoot);
-  const dir = path.dirname(filePath);
-
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-
-  const tempPath = `${filePath}.tmp`;
-  fs.writeFileSync(tempPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
-  fs.renameSync(tempPath, filePath);
+  writeJsonAtomic(filePath, data);
 }
 
 /**

package/lib/circuit-breaker.js

@@ -0,0 +1,195 @@
+/**
+ * Antigravity AI Kit — Circuit Breaker
+ *
+ * Implements the circuit breaker pattern for protecting external
+ * operations (git clones, network requests) from cascading failures.
+ *
+ * States: CLOSED (normal) → OPEN (failing) → HALF_OPEN (testing recovery)
+ *
+ * @module lib/circuit-breaker
+ * @author Emre Dursun
+ * @since v3.2.0
+ */
+
+'use strict';
+
+/** @typedef {'CLOSED' | 'OPEN' | 'HALF_OPEN'} CircuitState */
+
+/**
+ * @typedef {object} CircuitBreakerOptions
+ * @property {number} [failureThreshold=3] - Failures before opening circuit
+ * @property {number} [resetTimeoutMs=60000] - Time before attempting recovery (ms)
+ * @property {number} [halfOpenMaxAttempts=1] - Max attempts in half-open state
+ */
+
+/**
+ * @typedef {object} CircuitBreakerState
+ * @property {CircuitState} state - Current circuit state
+ * @property {number} failureCount - Consecutive failure count
+ * @property {number} successCount - Consecutive success count in half-open
+ * @property {number | null} lastFailureTime - Timestamp of last failure
+ * @property {number} totalFailures - Lifetime failure count
+ * @property {number} totalSuccesses - Lifetime success count
+ */
+
+/**
+ * Creates a new circuit breaker instance.
+ *
+ * @param {string} name - Circuit breaker name for identification
+ * @param {CircuitBreakerOptions} [options] - Configuration options
+ * @returns {{ execute: Function, getState: Function, reset: Function }}
+ */
+function createCircuitBreaker(name, options = {}) {
+  const failureThreshold = options.failureThreshold || 3;
+  const resetTimeoutMs = options.resetTimeoutMs || 60000;
+  const halfOpenMaxAttempts = options.halfOpenMaxAttempts || 1;
+
+  /** @type {CircuitBreakerState} */
+  const state = {
+    state: 'CLOSED',
+    failureCount: 0,
+    successCount: 0,
+    lastFailureTime: null,
+    totalFailures: 0,
+    totalSuccesses: 0,
+  };
+
+  /**
+   * Checks if the circuit should transition from OPEN to HALF_OPEN.
+   *
+   * @returns {boolean}
+   */
+  function shouldAttemptReset() {
+    if (state.state !== 'OPEN' || state.lastFailureTime === null) {
+      return false;
+    }
+    return (Date.now() - state.lastFailureTime) >= resetTimeoutMs;
+  }
+
+  /**
+   * Records a successful operation.
+   *
+   * @returns {void}
+   */
+  function onSuccess() {
+    state.totalSuccesses += 1;
+
+    if (state.state === 'HALF_OPEN') {
+      state.successCount += 1;
+      if (state.successCount >= halfOpenMaxAttempts) {
+        state.state = 'CLOSED';
+        state.failureCount = 0;
+        state.successCount = 0;
+        state.lastFailureTime = null;
+      }
+    } else {
+      state.failureCount = 0;
+    }
+  }
+
+  /**
+   * Records a failed operation.
+   *
+   * @returns {void}
+   */
+  function onFailure() {
+    state.totalFailures += 1;
+    state.failureCount += 1;
+    state.lastFailureTime = Date.now();
+
+    if (state.state === 'HALF_OPEN') {
+      state.state = 'OPEN';
+      state.successCount = 0;
+    } else if (state.failureCount >= failureThreshold) {
+      state.state = 'OPEN';
+    }
+  }
+
+  /**
+   * Executes an operation through the circuit breaker.
+   *
+   * @param {Function} operation - Async or sync operation to execute
+   * @returns {*} Result of the operation
+   * @throws {Error} If circuit is open or operation fails
+   */
+  function execute(operation) {
+    if (state.state === 'OPEN') {
+      if (shouldAttemptReset()) {
+        state.state = 'HALF_OPEN';
+        state.successCount = 0;
+      } else {
+        throw new Error(
+          `Circuit breaker "${name}" is OPEN — operation rejected. ` +
+          `${state.failureCount} consecutive failures. ` +
+          `Will retry after ${Math.ceil((resetTimeoutMs - (Date.now() - state.lastFailureTime)) / 1000)}s.`
+        );
+      }
+    }
+
+    try {
+      const result = operation();
+      onSuccess();
+      return result;
+    } catch (error) {
+      onFailure();
+      throw error;
+    }
+  }
+
+  /**
+   * Executes an asynchronous operation through the circuit breaker.
+   * Properly tracks Promise resolution/rejection for state management.
+   *
+   * @param {Function} operation - Async operation to execute (must return a Promise)
+   * @returns {Promise<*>} Result of the operation
+   * @throws {Error} If circuit is open or operation fails
+   */
+  async function executeAsync(operation) {
+    if (state.state === 'OPEN') {
+      if (shouldAttemptReset()) {
+        state.state = 'HALF_OPEN';
+        state.successCount = 0;
+      } else {
+        throw new Error(
+          `Circuit breaker "${name}" is OPEN — operation rejected. ` +
+          `${state.failureCount} consecutive failures. ` +
+          `Will retry after ${Math.ceil((resetTimeoutMs - (Date.now() - state.lastFailureTime)) / 1000)}s.`
+        );
+      }
+    }
+
+    try {
+      const result = await operation();
+      onSuccess();
+      return result;
+    } catch (error) {
+      onFailure();
+      throw error;
+    }
+  }
+
+  /**
+   * Returns a snapshot of the circuit breaker state.
+   *
+   * @returns {CircuitBreakerState & { name: string }}
+   */
+  function getState() {
+    return { name, ...state };
+  }
+
+  /**
+   * Resets the circuit breaker to CLOSED state.
+   *
+   * @returns {void}
+   */
+  function reset() {
+    state.state = 'CLOSED';
+    state.failureCount = 0;
+    state.successCount = 0;
+    state.lastFailureTime = null;
+  }
+
+  return { execute, executeAsync, getState, reset };
+}
+
+module.exports = { createCircuitBreaker };