Completrix

Completrix is a self-governing, self-evolving architecture platform — starting as a deterministic compiler for systems and growing into an engine that understands, completes, converges, and evolves real systems under its own rules.

Where builders once accumulated fragments, half-finished ideas, and partial specs, Completrix introduces a governed, reproducible pathway from fragment to finished system. It enforces a universal schema, applies rule-based inference, generates execution plans, and produces governed outputs that downstream systems can execute safely.

Completrix is not a generator. It is a structural engine.

It transforms a sentence, a sketch, a partial spec, or a repo summary into a complete system specification, an execution plan of atomic tasks, a governance pack, and a validated export bundle for ArchitectAI, agents, and humans.

Completrix eliminates idea debt. It creates structural consistency across all projects. It enables deterministic system creation at scale.

Roadmap

Completrix evolves through six milestones — from a deterministic compiler to a fully self-governing platform.

| Milestone | Name | Status | Description | |---|---|---|---| | 1 | Understand Systems | ✅ Complete | Deterministic compiler: fragment → governed system spec via the 7-component schema pipeline | | 2 | Define Finished Systems | ✅ Complete | Completion profiler: produces module maps, repo blueprints, test scaffolds, CI rules, and governance profiles | | 3 | Move Systems Toward Completion | ✅ Complete | Convergence engine: applies deterministic mutations to close gaps and iterate a spec to stability | | 4 | Evolve Itself | ✅ Complete | Self-bootstrap engine: detects its own gaps, generates missing artifacts, and evolves its own architecture | | 5 | Become a Platform | ✅ Complete | CLI commands, stable JSON contracts, drift detection gates — a surface for humans, agents, and CI/CD | | 6 | The Full Loop | ✅ Complete | Compile → Complete → Converge: any fragment, any repo, including itself, run through the complete lifecycle |

Architecture

Milestone 1 — Compiler Pipeline

                      ┌──────────────────────┐
                      │        META          │
                      │  schema, invariants  │
                      └──────────┬───────────┘
                                 │
                                 ▼
                      ┌──────────────────────┐
                      │       INGEST         │
                      │ normalize + signals  │
                      └──────────┬───────────┘
                                 │
                                 ▼
                      ┌──────────────────────┐
                      │    STRUCTURE MAP     │
                      │ detect presence      │
                      └──────────┬───────────┘
                                 │
                                 ▼
                      ┌──────────────────────┐
                      │        INFER         │
                      │ rule packs + scores  │
                      └──────────┬───────────┘
                                 │
                                 ▼
                      ┌──────────────────────┐
                      │      FINAL FORM      │
                      │ canonical spec       │
                      └──────────┬───────────┘
                                 │
                                 ▼
                      ┌──────────────────────┐
                      │    EXECUTION PLAN    │
                      │ tasks + blueprint    │
                      └──────────┬───────────┘
                                 │
                                 ▼
                      ┌──────────────────────┐
                      │      GOVERNANCE      │
                      │ invariants + drift   │
                      └──────────┬───────────┘
                                 │
                                 ▼
                      ┌──────────────────────┐
                      │        EXPORT        │
                      │ AI + agents + human  │
                      └──────────┬───────────┘
                                 │
                                 ▼
                      ┌──────────────────────┐
                      │      PORTFOLIO       │
                      │ similarity + merge   │
                      └──────────────────────┘

Milestones 2–6 — The Full Loop

           ┌─────────────────────────────────────────────┐
           │               FULL LOOP ENGINE              │
           │         Compile → Complete → Converge       │
           └─────────────────────┬───────────────────────┘
                                 │
              ┌──────────────────┼──────────────────┐
              ▼                  ▼                  ▼
   ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
   │   COMPLETION     │ │   CONVERGENCE    │ │ SELF-BOOTSTRAP   │
   │   PROFILER       │ │   ENGINE         │ │ ENGINE           │
   │ (milestone 2)    │ │ (milestone 3)    │ │ (milestone 4)    │
   │                  │ │                  │ │                  │
   │ module map       │ │ detect gaps      │ │ scan filesystem  │
   │ repo blueprint   │ │ compute mutations│ │ gen modules      │
   │ test scaffold    │ │ apply mutations  │ │ gen contracts    │
   │ CI rules         │ │ iterate to stable│ │ gen governance   │
   │ governance prof  │ │                  │ │ evolution plan   │
   └──────────────────┘ └──────────────────┘ └──────────────────┘
              │                  │                  │
              └──────────────────┼──────────────────┘
                                 ▼
                      ┌──────────────────────┐
                      │   CLI / PLATFORM     │
                      │   (milestone 5)      │
                      │ init · generate      │
                      │ test · run           │
                      └──────────────────────┘

Pipeline

| Stage | Module | Description | |---|---|---| | 1 | Ingest | Normalize text, extract signals (verbs/nouns/roles), classify fragment type, score confidence | | 2 | StructureMap | Detect PRESENT/PARTIAL/MISSING for each of 7 schema components | | 3 | Infer | Apply deterministic rule packs to fill all components; compute COMPLETE/PARTIAL/REJECTED status | | 4 | FinalForm | Assemble validated FinalSystemSpec; derive architecture modules and execution flows | | 5 | ExecutionPlan | Generate atomic tasks, repo blueprint, CI rules, rule packs, migrations, hardening | | 6 | Governance | Derive invariants, constraints, drift rules, and auto-fix suggestions | | 7 | Export | Produce versioned bundles: ArchitectAI JSON, agent JSON, human Markdown |

7 Schema Components

| Component | Description | |---|---| | problem | Core problem definition and summary | | user | Primary and secondary user roles | | boundary | In-scope, out-of-scope, external dependencies | | dataModel | Entities and data structures | | executionModel | Operations and workflows | | interface | Interaction modes and actions | | completionCriteria | Success conditions |

Module Overview

Milestone 1 — Compiler Modules

| Path | Responsibility | |---|---| | src/meta/ | Schema versioning, invariants, change protocol | | src/ingest/ | Text normalization, signal extraction, fragment classification | | src/structure_map/ | Component presence detection (PresenceStatus) | | src/infer/ | Deterministic rule packs producing CompletedSchemaWithStatus | | src/final_form/ | System spec assembly, architecture derivation, flow derivation | | src/execution_plan/ | Task, repo, CI, rules, migration, and hardening generation | | src/governance/ | Invariants, constraints, drift detection, auto-fix suggestions | | src/export/ | Multi-format export (ArchitectAI / agents / humans) | | src/portfolio/ | Multi-spec similarity, conflict, and merge analysis | | src/shared/ | Shared types, models, and utility functions |

Milestone 2 — Completion Modules

| Path | Responsibility | |---|---| | src/completion/ | Completion profiler: module maps, test scaffolds, CI rules, governance profiles, completeness score |

Milestone 3 — Convergence Modules

| Path | Responsibility | |---|---| | src/convergence/ | Convergence engine: deterministic mutation loops to close gaps and reach stability |

Milestone 4 — Self-Evolution Modules

| Path | Responsibility | |---|---| | src/engine/evolution/ | Gap detection, module generation, contract synthesis, governance generation, evolution plan | | src/engine/selfBootstrap.ts | Self-bootstrap engine: runs Completrix on its own codebase | | src/autonomous/ | Autonomous clarification, creation, decomposition, portfolio evolution |

Milestones 5 & 6 — Platform & Full Loop Modules

| Path | Responsibility | |---|---| | src/cli/ | CLI commands: init, generate, test, run --self-bootstrap | | src/engine/compileCompleteConvergeLoop.ts | Full Compile → Complete → Converge loop |

Usage

Milestone 1 — Compile a fragment into a governed system spec

import { runCompletrix } from "./src/index.js";

const result = runCompletrix("Build a web platform for user account management with authentication");

if (result.kind === "REJECTION") {
  // result.clarificationQuestions: string[]
  throw new Error(`Insufficient signal. Ask: ${result.clarificationQuestions.join("; ")}`);
}

// result.bundle: ExportBundle
const { forHumans, forArchitectAI, forAgents } = result.bundle;

Milestone 2 — Profile the completed shape of a system

import { runCompileCompleteConvergeLoop, profileCompletion } from "./src/index.js";

const result = runCompileCompleteConvergeLoop(
  "Build a task management API with authentication and notifications"
);

// profile contains: moduleMap, repoBlueprint, testScaffold, ciRules, governanceProfile, gaps, completenessScore
const profile = profileCompletion(result.finalSpec);
console.log(`Completeness: ${(profile.completenessScore * 100).toFixed(0)}%`);
console.log("Gaps:", profile.gaps);
console.log("Modules:", profile.moduleMap.map(m => m.path));

Milestone 3 — Converge a partial spec toward a target

import { converge } from "./src/index.js";

// Move `partialSpec` toward `targetSpec` using deterministic mutations
const result = converge(partialSpec, targetSpec, /* maxIterations */ 10);
console.log(`Stable: ${result.stable}, iterations: ${result.iterations}`);
console.log("Applied mutations:", result.appliedMutations.map(m => m.description));

Milestone 4 — Run the self-bootstrap engine

import { selfBootstrap } from "./src/index.js";

// Completrix scans its own codebase, detects gaps, and generates evolution artifacts
const result = await selfBootstrap({ rootDir: process.cwd() });
if (result.stable) {
  console.log(`Stable after ${result.iterations} iteration(s)`);
} else {
  console.log("Evolution plan written to .completrix/");
}

Milestone 6 — Run the full Compile → Complete → Converge loop

import { runCompileCompleteConvergeLoop } from "./src/index.js";

const result = runCompileCompleteConvergeLoop(
  "Build a SaaS billing platform with subscription tiers and webhook notifications",
  { maxIterations: 5 }
);

console.log(`Stable: ${result.stable}, score: ${result.finalScore}`);
console.log("Applied mutations:", result.appliedMutations.map(m => m.description));
const { forHumans, forArchitectAI, forAgents } = result.bundle;

Portfolio Analysis

import { analyzeFragmentAgainstPortfolio } from "./src/index.js";

const analysis = analyzeFragmentAgainstPortfolio(newSpec, existingSpecs);
// { similarity: 0.72, conflicts: [...], recommendation: "extend" }

CLI

Completrix ships a governed CLI that exposes the full milestone surface:

completrix init --module <name> [--module <name>] [--atomic]
completrix generate --repo --contracts --governance --ci
completrix test --harness montecarlo --init
completrix run --self-bootstrap

| Command | Milestone | Description | |---|---|---| | completrix init | 5 | Scaffold a new governed module or system | | completrix generate | 5 | Generate repo blueprint, contracts, governance pack, and CI config | | completrix test | 5 | Run or initialize the Monte Carlo test harness | | completrix run --self-bootstrap | 4, 6 | Run the self-bootstrap engine: scan gaps, generate artifacts, iterate to stability |

Return Type

runCompletrix returns a discriminated union — callers can handle all cases programmatically:

type CompletrixResult =
  | { kind: "REJECTION"; clarificationQuestions: string[] }
  | { kind: "SUCCESS"; bundle: ExportBundle }

Schema Versioning

Current schema version: 2.0.0

| Bump | Rule | |---|---| | patch | Inference accuracy improvements | | minor | New rule packs (backwards-compatible) | | major | Schema changes (requires migration) |

Migration Rules

• v2.0 → v2.1: no breaking changes
• All new rule packs must be optional
• All new detectors must be additive
• All new exports must be version-tagged

Determinism Guarantees

• Same input always produces the same output.
• All pipeline functions are pure with no side effects.
• No global mutable state in any core module.
• Side-effectful operations (I/O, logging, network calls) are disallowed in core pipeline modules and enforced via linting (no-console rule in eslint.config.js).
• Determinism is verified by automated tests in tests/determinism.test.ts.

Governance

The governance layer derives invariants, constraints, drift rules, and auto-fix suggestions directly from the FinalSystemSpec. All invariants are machine-readable strings. Drift rules reference the declared boundary scope to flag scope creep.

ArchitectAI Integration Contract v1.0

Completrix exports a versioned bundle that ArchitectAI consumes deterministically:

{
  "exportVersion": "1.0.0",
  "schemaVersion": "2.0.0",
  "requiredFields": ["tasks", "repoBlueprint", "ciRules", "invariants"],
  "fields": {
    "tasks": { "type": "string[]", "description": "Atomic execution tasks generated by Completrix" },
    "repoBlueprint": { "type": "object", "description": "Deterministic folder/file structure for downstream code generation" },
    "ciRules": { "type": "string[]", "description": "Rules ArchitectAI must enforce in generated CI pipelines" },
    "rulePacks": { "type": "string[]", "description": "Rule packs ArchitectAI must load for code generation" },
    "invariants": { "type": "string[]", "description": "System invariants ArchitectAI must enforce" },
    "constraints": { "type": "string[]", "description": "Architectural constraints ArchitectAI must respect" },
    "autoFix": { "type": "string[]", "description": "Auto-fix suggestions ArchitectAI may apply" }
  },
  "validation": {
    "tasks": "must be non-empty",
    "repoBlueprint": "must contain src and tests",
    "ciRules": "must include test, lint, typecheck",
    "invariants": "must include determinism"
  }
}