# Forge

> Autonomous quality engineering swarm that forges production-ready code through continuous behavioral verification, exhaustive E2E testing, and self-healing fix loops. Combines DDD+ADR+TDD methodology with BDD/Gherkin specifications, 7 quality gates, defect prediction, chaos testing, and cross-context dependency awareness. Architecture-agnostic - works with monoliths, microservices, modular monoliths, and any bounded-context topology.

- Skill: `ikennaokpala/forge` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add ikennaokpala/forge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ikennaokpala/forge/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ikennaokpala (https://skillmd.com/u/ikennaokpala)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ikennaokpala/forge

---


# Forge - Autonomous Quality Engineering Swarm

**Quality forged in, not bolted on.**

Forge is a self-learning, autonomous quality engineering swarm that unifies three approaches into one:

| Pillar | Source | What It Does |
|--------|--------|--------------|
| **Build** | DDD+ADR+TDD methodology | Structured development with quality gates, defect prediction, confidence-tiered fixes |
| **Verify** | BDD/Gherkin behavioral specs | Continuous behavioral verification - the PRODUCT works, not just the CODE |
| **Heal** | Autonomous E2E fix loop | Test → Analyze → Fix → Commit → Learn → Repeat |

**"DONE DONE"** means: the code compiles AND the product behaves as specified. Every Gherkin scenario passes. Every quality gate clears. Every dependency graph is satisfied.

---

## TOPOLOGICAL GOVERNANCE FOUNDATIONS

Forge's autonomous pipeline is governed by topological invariants from the theory of topological governance in autonomous software engineering. Each subsection defines a formal specification that agents MUST follow. For infrastructure-dependent computations (Blake3, HNSW, WASM), the specification is defined with a readiness marker - agents approximate the computation via structured reasoning until native runtime is available.

**Notation convention:** Display equations use ` ```math ` blocks with LaTeX. Inline math uses Unicode Greek letters (λ, ρ, ε, β), operators (≤, ≥, ∈, ⊂, ⊇, ∘), and subscripts/superscripts from the Superscripts and Subscripts block (λ₂, β₀, H⁰, Fₙ). Letter subscripts outside that block use underscore (s_i, ρ_ij); letter superscripts use caret (B^d, H^*).

### 1.1 Sheaf-Theoretic Consistency Model

Bounded contexts form a topological space where each context U_i is an open set. Quality gates produce local sections s_i ∈ F(U_i) over each context. Global consistency is verified via sheaf cohomology:

- **H⁰(F) = global sections** - Gate results that agree across all context overlaps. When H⁰ is non-trivial, the swarm has achieved a globally consistent quality state.
- **H¹(F) ≠ 0 = inter-context inconsistency** - A non-zero first cohomology group signals that local gate passes cannot be reconciled globally. Example: context A's contract tests pass against schema v2, but context B's contract tests assume schema v1. Both pass locally; the system fails globally. **Action: If H¹(X; F) ≠ 0, REJECT the commit immediately. The codebase state cannot be glued consistently.**

**Restriction maps:** For contexts U_i ⊇ U_j, the restriction ρ_ij: F(U_i) → F(U_j) is the projection of gate results onto the sub-context. Gate Enforcer verifies the cocycle condition: ρ_ij ∘ ρ_jk = ρ_ik on triple overlaps.

**Mathematical anchors** (Betti numbers): β₀ = number of connected components in the context dependency graph (should be 1 for a well-connected system). β₁ = number of independent cycles (each cycle is a potential inconsistency loop requiring explicit contract validation).

**Operational mapping:** Forge's cross-context dependency validation (Phase 2) and cascade re-testing IS the computation of restriction maps. Gate 7 (Contract) failures on shared types ARE non-zero H¹ elements.

### 1.2 Sheaf Laplacian & Dirichlet Energy

The discrete Sheaf Laplacian L_F is defined on the context dependency graph G = (V, E) where V = bounded contexts and E = dependency edges:

```math
L_{\mathcal{F}} = D_{\mathcal{F}} - A_{\mathcal{F}}
```

where D_F is the degree matrix weighted by restriction map norms and A_F is the adjacency matrix weighted by inter-context agreement.

**Dirichlet energy** quantifies total system tension:

```math
E(S) = \sum_{(i,j) \in E} \left\|\rho_{ij}(s_i) - \rho_{ji}(s_j)\right\|^2
```

where s_i is context i's gate result vector and ρ_ij is the restriction map from context i to the shared boundary with context j.

**Operational mapping:** Forge's criticality score IS a discretized Dirichlet energy - the weighted combination of duration, blocking impact, cost, and detection rate across the agent graph measures the same "tension" that the Sheaf Laplacian formalizes. The stability threshold is E(S) ≤ 0.7. If E(S) > 0.7, the Hallucination Gate MUST close. The agent's generation is blocked and a Blake3 witness is generated detailing the topological constraint violated.

### 1.3 Persistent Sheaf Laplacian

The commit history defines a filtration F₀ ⊂ F₁ ⊂ ... ⊂ Fₙ where each Fₜ is the codebase state at commit t. The Persistent Sheaf Laplacian tracks how Dirichlet energy evolves across this filtration.

**Persistence barcodes** per Gherkin scenario:

| Bar Type | Meaning | Forge Classification |
|----------|---------|---------------------|
| **Long bar** (born early, still alive) | Scenario has been stable across many commits | **Stable** (10+ consecutive passes) |
| **Short bar** (born and dies quickly) | Scenario flickers between pass/fail | **Flaky** (alternating pass/fail) |
| **Died bar** (was alive, now dead) | Scenario was passing, now consistently fails | **Regressed** (was stable, now failing) |

**Operational mapping:** Forge's behavioral regression tracking - storing the last 50 results per scenario with stability scores (Stable/Flaky/Regressed) - IS the persistence diagram. The `first_failure_commit` field marks the birth of a homological feature (a new failure mode). The `stability_score` is the bar length normalized to [0, 1].

### 1.4 Hallucination Gate - Deterministic Binary Boundary

The Hallucination Gate is a 3-phase deterministic verification that runs BEFORE any LLM-as-Judge evaluation. It provides a binary PASS/FAIL boundary that cannot be fooled by probabilistic reasoning.

**Phase 1 - AST Symbol Resolution:**
Parse the fix diff's AST. Every referenced symbol (class, function, method, import, type) MUST resolve to an existing definition in the codebase or SDK. Unresolved symbols = immediate FAIL.

**Phase 2 - Contract Hash Verification:**
Compute SHA-256 hash of the API specification (OpenAPI/schema) before and after the fix. If the fix claims to be non-breaking but the contract hash changed, FAIL. Contract mutations require explicit declaration.

**Phase 3 - Internal Mocking Detection:**
Regex scan for `@patch`, `mock`, `stub`, `fake`, `spy` targeting internal module paths. Any match = immediate FAIL. This is Gate 4's existing deterministic check, elevated to the Hallucination Gate.

**Gate ordering:** Primary gate = Hallucination Gate (deterministic). Secondary gate = LLM-as-Judge (probabilistic). A fix MUST pass the deterministic gate before the probabilistic gate is consulted. This prevents the "circular validation trap" where an LLM evaluates another LLM's output.

**Operational mapping:** Bug Fixer's Self-Reflection Gate Step 3.5 dimension (e) "EXISTENCE CHECK" IS Phase 1. Gate 4's mocking detection IS Phase 3. This subsection elevates them to a formal pre-LLM boundary and adds Phase 2 (contract hash).

### 1.5 Blake3 Cryptographic Witness Chain

Every gate verdict produces a cryptographic witness record forming an append-only hash chain:

```json
{
  "witness_id": "w-[gate]-[timestamp]",
  "gate": "functional|behavioral|coverage|security|accessibility|resilience|contract",
  "input_hash": "SHA-256 of test inputs + source files evaluated",
  "output_hash": "SHA-256 of gate verdict + evidence",
  "verdict": "PASS|FAIL",
  "timestamp": "ISO-8601",
  "prev_witness_hash": "SHA-256 of previous witness record in chain",
  "chain_position": "integer"
}
```

The chain is append-only - no witness can be modified after creation. Each witness references the previous, forming a tamper-evident log. Any break in the chain (hash mismatch) invalidates all subsequent witnesses.

**Infrastructure Dependency:** Blake3 hashing algorithm
**Readiness:** SPECIFICATION - agents use SHA-256 for witness hashing; computation is approximated via structured reasoning until Blake3 native runtime is available.
**Activation:** When Blake3 runtime is detected, agents switch from SHA-256 to Blake3 for witness hashing.

Witness records are stored in the `forge-witnesses` memory namespace with key pattern `witness-[gate]-[timestamp]`.

### 1.6 Algebraic Connectivity & Spectral Analysis

The agent collaboration graph G = (V, E) has 8 vertices (one per agent) and edges weighted by data flow volume between agents. The graph Laplacian L = D - A has eigenvalues 0 = λ₁ ≤ λ₂ ≤ ... ≤ λ₈.

**Fiedler value λ₂** = algebraic connectivity of the swarm:

**Hard requirement:** λ₂ MUST remain strictly > 0. A zero Fiedler value means the graph is disconnected - agents cannot coordinate.

| λ₂ Range | Classification | Action |
|----------|---------------|--------|
| λ₂ ≥ 0.5 | **Well-connected** | Swarm is healthy, agents communicate effectively |
| 0.1 ≤ λ₂ < 0.5 | **Weakly connected** | Monitor for emerging fragmentation |
| 0 < λ₂ < 0.1 | **Near-fragmentation** | Warning - strengthen inter-agent data flow |
| λ₂ ≈ 0 | **SWARM_FRAGMENTATION** | Instant MinCut isolation + forced synchronization event - agents are disconnected |

**Spectral analysis procedure:**
1. Construct adjacency matrix A from agent data flow (memory reads/writes between namespaces)
2. Compute degree matrix D = diag(row sums of A)
3. Compute Laplacian L = D - A
4. Extract λ₂ (second-smallest eigenvalue)
5. If λ₂ ≈ 0, execute MinCut isolation of disconnected subgraph + forced synchronization event. Emit SWARM_FRAGMENTATION alert to Learning Optimizer

**Operational mapping:** Forge's criticality scoring and bottleneck detection IS spectral analysis of the agent graph - bottleneck detection identifies agents with disproportionate blocking impact, which corresponds to vertices whose removal would disconnect the graph (low algebraic connectivity).

### 1.7 Dynamic MinCut Isolation

When an agent produces anomalous output (e.g., Bug Fixer generates a fix that fails the Hallucination Gate 3+ times consecutively), the system computes MinCut(G, anomalous_agent, Auto-Committer) to determine the minimum set of edges to sever to prevent anomalous output from reaching the commit stage.

**Quarantine protocol:**
1. Agent's output is logged but NOT forwarded to downstream agents
2. Failure Analyzer receives a QUARANTINE_ALERT with the agent's last 3 outputs
3. Learning Optimizer demotes all patterns applied by the quarantined agent (-0.10 each)
4. After root cause resolution, agent is un-quarantined and re-enters the pipeline

**Operational mapping:** Forge's sequential pipeline topology naturally provides MinCut = 1 per agent - each agent can be isolated by severing its single output edge. The blocking gate architecture (Gate Enforcer blocks Auto-Committer) IS a MinCut isolation boundary.

### 1.8 Hyperbolic Memory Architecture

Agent knowledge is embedded in the Poincaré ball model B^d = {x ∈ ℝ^d : ‖x‖ < 1} where hierarchical code relationships are preserved by hyperbolic distance:

```math
d_H(u, v) = \operatorname{arcosh}\!\left(1 + \frac{2\|u - v\|^2}{(1 - \|u\|^2)(1 - \|v\|^2)}\right)
```

This metric naturally represents code taxonomy: packages near the origin are high-level abstractions; leaves near the boundary are concrete implementations. Parent-child distances are short; cross-branch distances are exponentially large.

**HNSW (Hierarchical Navigable Small World) index** over Poincaré embeddings enables O(log n) similarity search across the knowledge base - finding the most relevant fix pattern for a novel failure in sub-millisecond time.

**Infrastructure Dependency:** Vector database with hyperbolic distance metric + HNSW index
**Readiness:** SPECIFICATION - agents follow the hierarchical namespace structure; retrieval is approximated via key-based lookups across 10 namespaces until native vector DB is available.
**Activation:** When HNSW-capable vector DB is detected (or AQE ReasoningBank is available), agents switch from key-based to vector-similarity retrieval.

**Operational mapping:** Forge's 10 memory namespaces (forge-patterns, forge-results, forge-state, forge-commits, forge-screens, forge-specs, forge-contracts, forge-predictions, forge-criticality, forge-witnesses) ARE a flat approximation of the Poincaré ball - each namespace represents a region of the knowledge space. The Intelligence Plane is realized when these namespaces are backed by hyperbolic embeddings.

### 1.9 GF(3) Triadic Validation

Pipeline phase transitions are governed by Galois field GF(3) = {-1, 0, +1} trit values where:

| GF(3) Trit | Role | Meaning |
|------------|------|---------|
| -1 | Generator | Agent that produces output (e.g., Bug Fixer generates a fix) |
| 0 | Coordinator | Agent that orchestrates flow (e.g., Gate Enforcer routes decisions) |
| +1 | Validator | Agent that verifies correctness (e.g., Test Runner validates behavior) |

**Conservation law:** For any interacting triad of agents, the GF(3) sum MUST equal 0 (mod 3). Every generation (-1) must be balanced by a validation (+1) through a coordinator (0). If sum ≠ 0, block the transition and generate Narya-proofs documenting the conservation violation.

**Phase mapping:**

| Phase | GF(3) Index | Must Complete Before |
|-------|-------------|---------------------|
| Plan | 0 | Specify |
| Specify | 1 | Test |
| Test | 2 | Analyze |
| Analyze | 3 | Fix |
| Fix | 4 | Gate |
| Gate | 5 | Commit |
| Commit | 6 | Learn |
| Learn | 7 | Next iteration |

**Operational mapping:** Forge's "Plan Before Execute" mandate and sequential pipeline IS the operational implementation of GF(3) conservation. The blocking gate architecture enforces that no phase can be skipped - each phase's output is the next phase's input. The Generator→Coordinator→Validator triad maps directly to Forge's Bug Fixer(-1)→Gate Enforcer(0)→Test Runner(+1) cycle: -1 + 0 + 1 ≡ 0 (mod 3).

### 1.10 Narya-Proofs - Counterfactual Verification

Every Bug Fixer fix generates a Narya-proof: a bidirectional type-checking artifact that proves the fix is both necessary and sufficient.

**Forward type-check:** Apply the fix → run targeted tests → all PASS. This proves the fix is sufficient (it resolves the failure).

**Backward type-check:** Remove the fix (revert) → run targeted tests → at least one FAIL. This proves the fix is necessary (without it, the failure persists).

**Valid Narya-proof:** forward = PASS AND backward = FAIL.

| Forward | Backward | Verdict | Interpretation |
|---------|----------|---------|---------------|
| PASS | FAIL | **VALID** | Fix is necessary and sufficient |
| PASS | PASS | **COINCIDENTAL** | Fix is not the actual cause - tests pass without it |
| FAIL | FAIL | **INSUFFICIENT** | Fix does not resolve the failure |
| FAIL | PASS | **IMPOSSIBLE** | Logical contradiction - investigate test flakiness |

**Infrastructure Dependency:** Automated bidirectional test execution with git stash/unstash
**Readiness:** SPECIFICATION - agents follow the forward+backward verification protocol; full automation requires git-level rollback integration.
**Activation:** When forge-witnesses namespace is active, Narya-proofs are stored as `narya-[fix-hash]` entries.

**Operational mapping:** Bug Fixer's "targeted test re-run after fix" IS the forward type-check. The backward type-check is the new formal requirement - it ensures fixes are not coincidental.

### 1.11 Sublinear Coverage via Johnson-Lindenstrauss

For large test suites (n > 1000 tests), the Johnson-Lindenstrauss lemma guarantees that random projection from n dimensions to O(log n) dimensions preserves pairwise distances within (1 ± ε) factor.

**Application:** Project n test cases onto O(log n) representative dimensions. Each dimension corresponds to a topological feature of the codebase (a module boundary, an API endpoint, a state machine transition). The representative subset covers the same topological features as the full suite with high probability.

**Projection:**

```math
\text{representative\_count} = O\!\left(\frac{\log n}{\varepsilon^2}\right)
```

For n = 1000 tests and ε = 0.1: representative_count ≈ 70 tests (93% reduction).

**Infrastructure Dependency:** Johnson-Lindenstrauss random projection matrix
**Readiness:** SPECIFICATION - agents use defect prediction to prioritize tests (greedy approximation of JL projection); full JL computation requires matrix operations.
**Activation:** When WASM runtime is available, agents compute exact JL projections for test selection.

**Operational mapping:** Forge's defect prediction ordering (predicted-to-fail first) IS a greedy approximation of JL projection - it selects the tests most likely to cover novel failure modes, achieving sublinear convergence without computing the full projection matrix.

### 1.12 WASM/Rust Execution Plane

Deterministic verification tasks are specified as pure functions suitable for WASM/Rust compilation:

| Task | Input | Output | Pure |
|------|-------|--------|------|
| Blake3 witness hashing | byte[] | hash | Yes |
| Eigenvalue computation (λ₂) | adjacency matrix | float | Yes |
| GF(3) phase validation | phase states | valid/invalid | Yes |
| HNSW nearest-neighbor | query vector, index | top-k results | Yes |
| Contract hash comparison | spec_before, spec_after | same/changed | Yes |
| JL random projection | test matrix, target dim | projected matrix | Yes |

**Infrastructure Dependency:** WASM runtime (e.g., Wasmtime, Wasmer) with Rust toolchain
**Readiness:** SPECIFICATION - all tasks are defined as pure functions; agents execute equivalent logic via structured reasoning until WASM runtime is available.
**Activation:** When WASM runtime is detected, deterministic tasks are offloaded from LLM reasoning to compiled execution for guaranteed correctness and sub-millisecond latency.

---

## ARCHITECTURE ADAPTABILITY

Forge adapts to any project architecture. Before first run, it discovers your project structure:

### Supported Architectures

| Architecture | How Forge Adapts |
|-------------|-----------------|
| **Monolith** | Single backend process, all contexts in one codebase. Forge runs all tests against one server. |
| **Modular Monolith** | Single deployment with bounded contexts as modules. Forge discovers modules and tests each context independently. |
| **Microservices** | Multiple services. Forge discovers service endpoints, tests each service, validates inter-service contracts. |
| **Monorepo** | Multiple apps/packages in one repo. Forge detects workspace structure (Turborepo, Nx, Lerna, Melos, Cargo workspace). |
| **Mobile + Backend** | Frontend app with backend API. Forge starts backend, then runs E2E tests against it. |
| **Full-Stack Monolith** | Frontend and backend in same deployment. Forge tests through the UI layer against real backend. |

### Project Discovery

On first invocation, Forge analyzes the project to build a context map:

```bash
# Forge automatically discovers:
# 1. Backend technology (Rust/Cargo, Node/npm, Python/pip, Go, Java/Maven/Gradle, .NET)
# 2. Frontend technology (Flutter, React, Next.js, Vue, Angular, SwiftUI, Kotlin/Compose)
# 3. Test framework (integration_test, Jest, Pytest, Go test, JUnit, xUnit)
# 4. Project structure (monorepo layout, service boundaries, module boundaries)
# 5. API protocol (REST, GraphQL, gRPC, WebSocket)
# 6. Build system (Make, npm scripts, Gradle tasks, Cargo features)
```

Forge stores the discovered project map:

```json
{
  "architecture": "mobile-backend",
  "backend": {
    "technology": "rust",
    "buildCommand": "cargo build --release --features test-endpoints",
    "runCommand": "cargo run --release --features test-endpoints",
    "healthEndpoint": "/health",
    "port": 8080,
    "migrationCommand": "cargo sqlx migrate run"
  },
  "frontend": {
    "technology": "flutter",
    "testCommand": "flutter drive --driver=test_driver/integration_test.dart --target={target}",
    "testDir": "integration_test/e2e/",
    "specDir": "integration_test/e2e/specs/"
  },
  "contexts": ["identity", "orders", "payments", "..."],
  "testDataSeeding": {
    "method": "api",
    "endpoint": "/api/v1/test/seed",
    "authHeader": "X-Test-Key"
  }
}
```

### Configuration Override

Projects can provide a `forge.config.yaml` at the repo root to override auto-discovery:

```yaml
# forge.config.yaml (optional - Forge auto-discovers if absent)
architecture: microservices
backend:
  services:
    - name: auth-service
      port: 8081
      healthEndpoint: /health
      buildCommand: npm run build
      runCommand: npm start
    - name: payment-service
      port: 8082
      healthEndpoint: /health
      buildCommand: npm run build
      runCommand: npm start
frontend:
  technology: react
  testCommand: npx cypress run --spec {target}
  testDir: cypress/e2e/
  specDir: cypress/e2e/specs/
contexts:
  - name: identity
    testFile: auth.cy.ts
    specFile: identity.feature
  - name: payments
    testFile: payments.cy.ts
    specFile: payments.feature
dependencies:
  identity:
    blocks: [payments, orders]
  payments:
    depends_on: [identity]
    blocks: [orders]
```

---

## MOCKING POLICY: EXTERNAL ONLY, NEVER INTERNAL

**RULE: Mock ONLY external services. NEVER mock internal code.**

All tests run against the REAL backend API. Internal services, repositories, controllers, and models are NEVER mocked. Only third-party services outside your system boundary may be mocked or stubbed.

**Production Evidence:** In production orchestra runs, 5/5 PR failures (100%) were traced to internal mocking violations. 5/5 PR successes (100%) used real implementations. (See Issues #24, #25)

### Allowed - External Services Only

These are outside your system boundary and may be mocked:

- **Payment processors:** Stripe, PayPal, Braintree
- **Cloud services:** Firebase, AWS, GCP, Azure
- **Communication:** Twilio, SendGrid, Mailgun
- **Third-party APIs:** Google Places, Plaid, OAuth providers
- **HTTP clients:** Dio, Axios, fetch (when calling external URLs)
- **Infrastructure:** File system, network layer, system clock

### Forbidden - Internal Code (NEVER Mock)

These are inside your system and must use real implementations:

- **Your own services:** UserService, OrderService, PaymentService, ApiService
- **Models & entities:** User, Order, Payment, any domain object
- **Repositories & data access:** UserRepository, OrderRepository
- **Controllers & providers:** Any application-layer code you wrote
- **AI-generated code:** Any code produced by Forge or other agents

### Testing Strategy by Layer

| Layer | Approach |
|-------|----------|
| **Integration tests** | Real services + in-memory database, mock only external APIs |
| **E2E/BDD tests** | Real backend running locally, real API calls, real database |
| **Contract tests** | Real API responses compared against expected schemas |

### Examples

```python
# GOOD: Mock external Stripe API
@patch("src.services.stripe_client.StripeClient.create_charge")
async def test_payment_flow(mock_stripe):
    mock_stripe.return_value = {"id": "ch_test", "status": "succeeded"}
    response = await client.post("/api/v1/payments", json=payment_data)
    assert response.status_code == 201  # Real service, real DB, mocked Stripe

# BAD: Mock internal OrderService - NEVER DO THIS
@patch("src.services.order_service.OrderService.create_order")  # ❌ VIOLATION
async def test_checkout(mock_order):
    mock_order.return_value = Order(id=1)  # Hides real integration bugs
    ...

# CORRECT: Real implementation with test database
async def test_checkout():
    response = await client.post("/api/v1/checkout", json=checkout_data)
    assert response.status_code == 201  # Real OrderService, real DB
    order = await db.get(Order, response.json()["data"]["id"])
    assert order is not None  # Verify real data flow
```

### Enforcement

- **Coverage Validator:** Scans test files for internal mocking patterns - flags as CRITICAL violation
- **Gate 4 (Security):** Includes internal mocking check - BLOCKS commit if detected
- **Auto-Committer:** Refuses to commit code containing internal mock patterns
- **Pattern:** Any `@patch`, `mock`, `stub`, `fake`, `spy` targeting internal module paths triggers a BLOCK

---

## MANDATORY: PLAN BEFORE EXECUTE

**Every Forge invocation MUST call `EnterPlanMode` before executing any tasks - no exceptions.**

Before any phase begins, Forge enters planning mode to establish:

1. **Task breakdown** - discrete units of work derived from the target context
2. **Scope boundaries** - what is in-scope vs. out-of-scope for this run
3. **Success criteria** - measurable outcomes mapped to the 7 quality gates
4. **Dependencies** - backend readiness, test data, external service stubs
5. **Strategy** - execution order, model routing, and iteration budget

**No task execution begins without an approved plan.** This applies to all invocation modes: full swarm, single-gate re-runs, and targeted fixes. The plan is the contract between Forge and the developer - it ensures alignment before autonomous work starts.

---


## PHASE 0: BACKEND SETUP (MANDATORY FIRST STEP)

**BEFORE ANY TESTING, the backend MUST be built, compiled, and running.**

This is the FIRST thing the skill does - no exceptions.

### Step 1: Check and Start Backend

```bash
# 1. Read project config or auto-discover backend settings
# 2. Check if backend is already running
curl -s http://localhost:${BACKEND_PORT}/${HEALTH_ENDPOINT} || {
  echo "Backend not running. Starting..."

  # 3. Navigate to backend directory
  cd ${BACKEND_DIR}

  # 4. Ensure environment is configured
  cp .env.example .env 2>/dev/null || true

  # 5. Build the backend
  ${BUILD_COMMAND}

  # 6. Run database migrations (if applicable)
  ${MIGRATION_COMMAND}

  # 7. Start backend (background)
  nohup ${RUN_COMMAND} > backend.log 2>&1 &
  echo $! > backend.pid

  # 8. Wait for backend to be healthy (up to 60 seconds)
  for i in {1..60}; do
    if curl -s http://localhost:${BACKEND_PORT}/${HEALTH_ENDPOINT} | grep -q "ok\|healthy\|UP"; then
      echo "Backend healthy on port ${BACKEND_PORT}"
      break
    fi
    sleep 1
  done
}
```

### Step 2: Verify Backend Health

```bash
# Verify critical endpoints are responding
curl -s http://localhost:${BACKEND_PORT}/${HEALTH_ENDPOINT} | jq .

# Verify test fixtures endpoint (for seeding)
curl -s -H "${TEST_AUTH_HEADER}" http://localhost:${BACKEND_PORT}/${TEST_STATUS_ENDPOINT} | jq .
```

### Step 3: Contract Validation

```bash
# Verify API spec matches running API (if OpenAPI/Swagger available)
curl -s http://localhost:${BACKEND_PORT}/${OPENAPI_ENDPOINT} > /tmp/live-spec.json

# Store contract snapshot for regression detection
npx @claude-flow/cli@latest memory store \
  --key "contract-snapshot-$(date +%s)" \
  --value "$(cat /tmp/live-spec.json | head -c 5000)" \
  --namespace forge-contracts
```

### Step 4: Seed Test Data (Real API Calls)

```bash
# Seed test data through REAL API - adapt to your project's seeding endpoint
curl -X POST http://localhost:${BACKEND_PORT}/${SEED_ENDPOINT} \
  -H "Content-Type: application/json" \
  -H "${TEST_AUTH_HEADER}" \
  -d '${SEED_PAYLOAD}'
```

---

## PHASE 1: BEHAVIORAL SPECIFICATION & ARCHITECTURE RECORDS

**Before testing, verify Gherkin specs and architecture decision records exist for the target bounded context.**

Behavioral specifications define WHAT the product does from the user's perspective. Every test traces back to a Gherkin scenario. If tests pass but specs fail, the product is broken.

### Spec Location

Gherkin specs are stored alongside tests:

```
${SPEC_DIR}/
├── [context-a].feature
├── [context-b].feature
├── [context-c].feature
└── ...
```

The exact location depends on your project's test structure. Forge auto-discovers this from the project map.

### Spec-to-Test Mapping

Each Gherkin `Scenario` maps to exactly one test function. The mapping is tracked:

```gherkin
Feature: [Context Name]
  As a [user role]
  I want to [action]
  So that [outcome]

  Scenario: [Descriptive scenario name]
    Given [precondition]
    When [action]
    Then [expected result]
    And [additional verification]
```

### Missing Spec Generation

If specs are missing for a target context, the Specification Verifier agent creates them:

1. Read the screen/component/route implementation files for the context
2. Extract all user-visible features, interactions, and states
3. Generate Gherkin scenarios covering every cyclomatic path
4. Write to `${SPEC_DIR}/[context].feature`
5. Map each scenario to its corresponding test function

### Spec Drift Detection

Gherkin specs are the behavioral contract. When specs and implementation diverge, the product is broken regardless of whether tests pass. Forge detects three types of drift:

**1. Static Drift - Code paths without matching specs**

Parse Gherkin Given/When/Then steps and verify matching code paths exist in the implementation. Flag:
- Implementation paths with no corresponding scenario (untested behavior)
- Scenarios referencing code paths that no longer exist (stale specs)
- New API endpoints with no behavioral specification

**2. Contract Drift - API specs vs live responses**

Compare API contracts defined in Gherkin scenarios against actual API responses:
- Expected response fields vs actual response fields
- Expected status codes vs actual status codes
- Expected error formats vs actual error formats

**3. Behavioral Regression Tracking**

Store the last N results (default: 50) per scenario to detect regressions over time:

```json
{
  "scenario": "User can complete payment",
  "history": [true, true, true, true, false],
  "stability_score": 0.80,
  "consecutive_passes_before_fail": 4,
  "first_failure_commit": "abc123",
  "status": "REGRESSED"
}
```

- **Stable** (10+ consecutive passes): scenario is reliable
- **Flaky** (alternating pass/fail): scenario needs investigation
- **Regressed** (was stable, now failing): high-priority alert with commit correlation

**Drift Severity Levels:**

| Severity | Meaning | Action |
|----------|---------|--------|
| **BLOCKING** | Implementation exists with no spec, or spec references removed code | Must resolve before Gate 2 |
| **WARNING** | Contract field mismatch or flaky scenario detected | Report in gate results, investigate |
| **INFO** | Minor drift (e.g., spec wording vs implementation naming) | Log for review |

### Agent-Optimized ADR Generation

When Forge discovers a bounded context without an Architecture Decision Record, the Specification Verifier generates one. ADRs follow an agent-optimized format designed for machine consumption:

```markdown
# ADR-NNN: [Context] Architecture Decision

## Status
Proposed | Accepted | Deprecated | Superseded by ADR-XXX

## MUST
- [Explicit required behaviors with contract references]
- [Link to OpenAPI spec: /api/v1/[context]/openapi.json]
- [Required integration patterns]

## MUST NOT
- [Explicit forbidden patterns]
- [Anti-patterns to avoid]
- [Coupling violations]

## Verification
- Command: [command to verify this decision holds]
- Expected: [expected output or exit code]

## Dependencies
- Depends on: [list of upstream contexts with ADR links]
- Blocks: [list of downstream contexts with ADR links]
```

**ADR Storage:**
- ADRs are stored in `docs/decisions/` or the project-configured ADR directory
- Each bounded context has exactly one ADR
- ADRs are updated when contracts change or new dependencies are discovered
- The Specification Verifier agent includes ADR generation in its workflow

---

## PHASE 2: CONTRACT & DEPENDENCY VALIDATION

### Contract Validation

Before running tests, verify API response schemas match expected DTOs:

```bash
# For each endpoint the context uses:
# 1. Make a real API call
# 2. Compare response structure against expected DTO/schema
# 3. Flag any mismatches as contract violations
```

Contract violations are treated as Gate 7 failures and must be resolved before functional testing proceeds.

### Shared Types Validation

For bounded contexts that share dependencies, validate type consistency across context boundaries:

1. **Identify shared DTOs/models** - For each context, extract types used in API requests and responses
2. **Cross-reference types** - Compare DTOs between contexts that share dependencies (from the dependency graph)
3. **Flag type mismatches** - e.g., context A expects `userId: string` but context B sends `userId: number`
4. **Validate value objects** - Ensure value objects (email, money, address) follow consistent patterns across contexts
5. **Report violations** - Flag as pre-Gate warnings with specific file locations and expected vs actual types

```json
{
  "sharedTypeViolation": {
    "type": "UserId",
    "contextA": { "name": "payments", "file": "types/payment.ts", "definition": "string" },
    "contextB": { "name": "orders", "file": "types/order.ts", "definition": "number" },
    "severity": "error"
  }
}
```

### Cross-Cutting Foundation Validation

Verify cross-cutting concerns are consistent across all bounded contexts:

- **Auth patterns** - Same header format (`Authorization: Bearer <token>`), same token validation approach across all endpoints
- **Error response format** - All API endpoints return errors in the project's standard format (consistent structure, error codes, HTTP status codes)
- **Logging patterns** - Consistent log levels, structured format, and correlation IDs across contexts
- **Pagination format** - Consistent pagination parameters and response format across collection endpoints

Cross-cutting violations are reported as warnings before Gate evaluation begins.

### Dependency Graph

Bounded contexts have dependencies. When a fix touches context X, all contexts that depend on X must be re-tested.

```yaml
# Context Dependency Map - define in forge.config.yaml or auto-discover
# Example for a typical application:
#
# authentication:
#   depends_on: []
#   blocks: [orders, payments, profile, messaging]
#
# payments:
#   depends_on: [authentication]
#   blocks: [orders, subscriptions]
#
# orders:
#   depends_on: [authentication, payments]
#   blocks: [reviews, notifications]
```

### Cascade Re-Testing

When Bug Fixer modifies a file in context X:

1. Identify which context X belongs to
2. Look up all contexts in `blocks` list for X
3. After X's tests pass, automatically re-run tests for blocked contexts
4. If a cascade failure occurs, trace it back to the original fix

---

## PHASE 3: SWARM INITIALIZATION

```bash
# Initialize anti-drift swarm for Forge
npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 10 --strategy specialized

# Load previous fix patterns from memory
npx @claude-flow/cli@latest memory search --query "forge fix patterns" --namespace forge-patterns

# Check current coverage and gate status
npx @claude-flow/cli@latest memory retrieve --key "forge-coverage-status" --namespace forge-state

# Load confidence tiers
npx @claude-flow/cli@latest memory search --query "confidence tier" --namespace forge-patterns

# Check defect predictions for target context
npx @claude-flow/cli@latest memory search --query "defect prediction" --namespace forge-predictions
```

---

## MODEL ROUTING

Forge routes each agent to the appropriate model tier based on task complexity, optimizing for cost without sacrificing quality:

| Agent | Model | Rationale |
|-------|-------|-----------|
| Specification Verifier | `sonnet` | Reads code + generates Gherkin - moderate reasoning |
| Test Runner | `haiku` | Structured execution, output parsing - low reasoning |
| Failure Analyzer | `sonnet` | Root cause analysis - moderate reasoning |
| Bug Fixer | `opus` | First-principles code fixes - high reasoning |
| Quality Gate Enforcer | `haiku` | Threshold comparison - low reasoning |
| Accessibility Auditor | `sonnet` | Code analysis + WCAG rules - moderate reasoning |
| Auto-Committer | `haiku` | Git operations, message formatting - low reasoning |
| Learning Optimizer | `sonnet` | Pattern analysis, prediction - moderate reasoning |

Projects can override model assignments in `forge.config.yaml`:

```yaml
# forge.config.yaml - Model routing overrides (optional)
model_routing:
  spec-verifier: sonnet
  test-runner: haiku
  failure-analyzer: sonnet
  bug-fixer: opus
  gate-enforcer: haiku
  accessibility-auditor: sonnet
  auto-committer: haiku
  learning-optimizer: sonnet
```

When no override is specified, the defaults above are used. This routing reduces token cost by ~60% compared to running all agents on the highest-tier model.

### Energy-Based Lane Routing

The static agent-to-model mapping above serves as the default. At runtime, Coherence Energy (E) dynamically refines routing by selecting the appropriate processing lane for each task:

| Lane | Energy Range | Processing | Latency | Description |
|------|-------------|------------|---------|-------------|
| **Reflex** | E < 0.1 | WASM engine / ruleset | < 1ms | Zero LLM calls - deterministic checks (threshold comparisons, hash validations, format checks) |
| **Retrieval** | 0.1 ≤ E < 0.4 | Haiku-tier + RAG | ~10ms | Pattern-matched responses with retrieval-augmented context from forge-patterns |
| **Heavy** | 0.4 ≤ E < 0.7 | Opus-tier deep analysis | ~100ms | First-principles reasoning for novel failures and complex fixes |
| **Escalation** | E ≥ 0.7 | Pause swarm | Human review | Dirichlet energy exceeds stability threshold - swarm pauses and escalates to human |

**How it works:** The existing UpgradeModel/DowngradeModel recommendations in criticality scoring already approximate energy-based routing. This formalizes those heuristics: when criticality is low (E < 0.1), skip the LLM entirely; when criticality exceeds the Dirichlet stability threshold (E ≥ 0.7), stop autonomous operation.

**Lane selection rule:** For each agent task, compute Coherence Energy E from the criticality score. The lane determines the model tier regardless of the agent's static default - a Gate Enforcer task that normally runs on haiku will escalate to opus if E ∈ [0.4, 0.7), or pause the swarm entirely if E ≥ 0.7.

---

## PHASE 4: SPAWN AUTONOMOUS AGENTS

Claude Code MUST spawn these 8 agents in a SINGLE message with `run_in_background: true`:

```javascript
// Agent 1: Specification Verifier
Task({
  model: "sonnet",
  prompt: `You are the Specification Verifier agent. Your mission:

    1. VERIFY backend is running: curl -sf http://localhost:${BACKEND_PORT}/${HEALTH_ENDPOINT}
    2. Check if Gherkin specs exist for the target bounded context:
       - Look in the project's spec directory
    3. If specs are MISSING:
       - Read the screen/component/route implementation files for the context
       - Extract all user-visible features, interactions, states
       - Generate Gherkin feature files with scenarios for every cyclomatic path
       - Write specs to the correct location
    4. If specs EXIST:
       - Read current implementations
       - Compare against existing scenarios
       - Flag scenarios that no longer match implementation (stale specs)
       - Generate new scenarios for uncovered features
       - Run drift analysis: static drift (code paths vs spec steps),
         contract drift (API schema vs spec expectations),
         behavioral regression (historical pass/fail trends)
    5. Create spec-to-test mapping:
       - Each Scenario name → test function name
       - Store mapping in memory for Test Runner
    6. Store results:
       npx @claude-flow/cli@latest memory store --key "specs-[context]-[timestamp]" \
         --value "[spec status JSON]" --namespace forge-specs

    CONSTRAINTS:
    - NEVER generate specs for code you haven't read
    - NEVER assume UI elements exist without checking implementation
    - NEVER create scenarios that duplicate existing coverage
    - NEVER modify existing test files - only spec files

    ACCEPTANCE:
    - Every implementation file has at least one Gherkin scenario
    - Spec-to-test mapping has zero unmapped entries
    - All generated scenarios follow Given/When/Then format
    - Results stored in forge-specs namespace

    Output: List of all Gherkin scenarios with their mapped test funct

…(truncated)