ArchHarness: Making Architecture Reviews Reproducible with Deterministic Gates & Provenance

Most architecture review problems are not judgment problems but reproducibility problems. Standards exist and reviews happen, yet a minor diagram label change regenerates artifacts, leaving the original approved version untraceable. Months later, no one can identify which version was approved or why.

The typical fix adds process. ArchHarness takes a different approach: make the checkable half of the work truly checkable with deterministic code, while not requiring language models to serve as the source of structural truth.

What It Is

ArchHarness is an enterprise architecture skill pack supporting Claude Code, OpenCode, Codex, GitHub Copilot, and Cursor. It provides 14 expert skills covering the full lifecycle, a real CLI ( python -m archharness), and multi-project workspaces.

The pipeline is mandatory and controlled by artifact gates: a stage starts only when all required inputs are present. Skipping or forging upstream artifacts is not allowed.

需求 → 设计 → 出图 → 验证 → 强制门禁
                         │ PASS / WARN → 安全评审 + 委员会评审
                         │ BLOCK       → 停止
安全评审 + 委员会评审 → 整改清单 → 报告

Core Philosophy: Structure to Deterministic Code, Judgment to Models

Models handle interpretation, critique, and prose; structure, layout, hashes, and gate decisions go to deterministic, locally testable code.

Three things are deliberately implemented as code:

1. Gates. archharness enforce reads validation/v1 results, applies versioned policy, and returns PASS / WARN / BLOCK with process exit codes. Default thresholds: score ≥ 8.0 and no must-fix → PASS; score ≥ 6.0 → WARN; score < 6.0 or any must-fix → BLOCK. Same input always yields the same conclusion, enabling CI integration.

2. Provenance. Every governed artifact is recorded as an artifact/v1 manifest: project-relative path, exact-byte SHA-256, producer, timestamp, and lineage. Changing an architecture diagram under a recorded decision causes the next gate to fail. archharness workflow verify re-checks on-disk files against the manifest.

3. Contracts. req/v2, artifact/v1, validation/v1, enforcement/v1, and metrics/v1. Contracts are versioned by identity: breaking changes must publish a new id. archharness schema-check enforces this in CI, not reviewer memory.

Quick Start

pip install "archharness[all]"
archharness doctor
# Load policies, workflow specs, and schemas
archharness init-workspace .
archharness init-project orders --name "Order Platform" --platform private_cloud --default

Fill input/systems-registry.md — the only file holding literal names; all other documents reference typed IDs (INF-, APP-, CMP-, DEP-, FLOW-, LNK-, AUTH-).

# Extract requirements from docs and generate gap report
archharness req --doc projects/orders/input/documents/requirements.md \
  -o projects/orders/output/requirements/req.yaml \
  --report projects/orders/output/validation/gap-report.md

# Objective checks before review cycles
archharness req-validate projects/orders/output/requirements/req.yaml
archharness arch-check -i projects/orders/output/designs/blueprint.yaml
archharness trace-check -r projects/orders/output/requirements/req.yaml \
  -b projects/orders/output/designs/blueprint.yaml

# Render diagrams — draw.io is editable source, images rendered by D2
archharness diagram -i projects/orders/output/designs/blueprint.yaml \
  -o projects/orders/output/diagrams/diagram-v1.drawio \
  --d2 projects/orders/output/diagrams/diagram-v1.d2 \
  --png projects/orders/output/diagrams/diagram-v1.png

The only model-driven step is validating rendered diagrams ( /arch-validate), producing validation/v1 results. Every subsequent step is deterministic:

archharness enforce --validation projects/orders/output/validation/validate_result.json \
  --output projects/orders/output/validation/enforce_result.json
# → decision: WARN  exit 0  (BLOCK exits 1)

archharness backlog -v projects/orders/output/validation/validate_result.json \
  -r projects/orders/output/requirements/req.yaml \
  -b projects/orders/output/designs/blueprint.yaml -o backlog.md

archharness workflow status   # What can start next
archharness workflow verify   # Do recorded artifacts still match disk?

Six Platform Standards, Not One

Describing a single cloud's architecture standard is essentially a configuration file. ArchHarness ships six — private cloud, AWS, Azure, Google Cloud, Alibaba Cloud, and Microsoft SaaS — each with placement models, region models, identity and secret handling, data classification, and corresponding validation rule families.

The repository includes 11 complete examples covering these standards, six mapping one-to-one. Each contains requirements, typed models, rendered architecture diagrams, and standard conformance checks. They serve as "what done looks like" references; CI re-renders every blueprint and re-validates every recorded digest, preventing silent drift.

Changes in 1.1.0

PNG now rendered by D2 by default. draw.io remains the editable source; draw.io rendering is an explicit option ( --png-engine drawio). The two serve different purposes: one for manual editing, one for review materials. --d2-scale / --d2-timeout for stable rendering of very large diagrams. archharness manifest to build artifact/v1 provenance docs from the CLI.

Privacy-preserving metrics/v1 aggregation ( archharness metrics): workflow completion, finding categories, diagram readability, stage latency — only counts and standard labels, never architecture payload.

Who It's For

Teams already doing architecture reviews and tired of manually re-proving the same facts; platform and security engineers who want standards enforced in pipelines, not meetings; and anyone who has been asked "Which version did we approve?" and couldn't answer.

Who It's Not For

If you want a tool that designs your system for you, this isn't it — and you should be wary of any tool claiming that. ArchHarness automates the checkable half; judgment is deliberately left to you.

Links

Repository: github.com/axisrobo/ea-harness Ten-minute walkthrough: docs/first-run.md CI recipes: docs/ci-pipeline.md 1.1.0 release:

github.com/axisrobo/ea-harness/releases/tag/v1.1.0