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:

"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:

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:

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:

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:

{
  "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.

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:

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:

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:

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.

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:

\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:

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

Project Discovery

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

# 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:

{
  "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:

# 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

Examples

# 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

# 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

# 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

# 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)

# 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:

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:

{
  "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:

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:

# 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:

# 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

{
  "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.

# 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

# 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:

Projects can override model assignments in forge.config.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:

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:

// 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)