axiarch

# Axiarch (AX-ee-ark)

> 版数とタグ参照はこのソースの公開対象版を示します。未マージのリリース準備ブランチでは未公開の場合があります。導入前に [公開済みRelease](https://github.com/hiroyuki-miyauchi/axiarch/releases/latest) を確認してください。
> Version metadata and tag references identify this source's intended release. They may be unpublished on an unmerged release-preparation branch; check the published Release before installation.

> Current Release: 1.18.0 | Latest Stable: 1.18.0

> Constitution-Driven AI Agent Governance Framework

Axiarch is an open-source governance framework that reduces the risk of quality
drift, hallucination, and uncontrolled behavior in AI-assisted software
development. It defines minimum quality standards across engineering, product,
security, operations, and business work through a multi-layer constitutional
architecture, making consistent output quality easier to maintain across agents
and operator skill levels.

## What Problem Does Axiarch Solve?

Without governance, AI agents suffer from:
- **Context amnesia**: Architectural decisions are forgotten between sessions
- **Operator-dependent quality**: Output quality varies with instruction precision
- **Vibe coding drift**: Code that looks correct but silently violates patterns
- **Knowledge evaporation**: Hard-won lessons are lost and re-discovered repeatedly

Axiarch mitigates these risks by defining a quality floor and autonomous context loading through constitutional architecture.
v1.12.0 adds explicit Harness Engineering: not a fourth rule layer, but the operational engineering that turns the three-layer model into execution order, audit gates, role passes, evidence packets, human approval boundaries, and optional subagent delegation.
Read-only subagent delegation is not a Human Approval Gate action by itself. When a user explicitly requests a deep audit, security scan, exhaustive review, Codex Security Deep Security Scan, or an equivalent named read-only workflow, that request includes the workflow's required read-only worker fanout. If delegation is unavailable, do not claim the formal deep workflow ran; use the documented ordinary scan or main-agent sequential role-pass fallback.

## Core Architecture (Three-Layer Governance)

- **Layer 1: Universal (Immutable Constitution)**
  - `AXIARCH.md` — Canonical Axiarch protocol; AGENTS.md and tool-native files are optional adapters. Only Google Antigravity has been validated in practical use, within the observed environments and tasks. OpenAI Codex, Claude Code and other agents are unverified; supplied adapters are compatibility candidates with no operation guarantee.
  - `axiarch-rules/{lang}/universal/` — 55 immutable rule files (3,000+ standards across engineering, product, security, operations, QA, AI, FinOps, and governance), including first-class programming-language portfolio, React Native, cloud/application-platform, Microsoft Azure, and polyglot delivery governance.
- **Layer 2: Blueprint (Mutable Project State)**
  - `axiarch-rules/{lang}/blueprint/` — Evolving project memory. Project overview, continuously accumulated lessons log, crystallized governance rules, and feature specs.
- **Layer 3: Prompts (Optional Execution Framework)**
  - `axiarch-prompts/` — Optional reusable audit/QA/upgrade execution prompt templates that make Layer 1/2 rules easier to apply to specific tasks.
- **Execution Harness**
  - `axiarch-harness/{lang}/` — Harness Engineering protocols for execution, audit, role pass, evidence, human approval, and optional subagent delegation; mandatory for non-trivial (H2+) work.

## Key Protocols

- **axiarch-rules/{lang}/LOADING_PROTOCOL.md**: 5-step rule hierarchy loading sequence
- **axiarch-rules/{lang}/CRYSTALLIZATION_PROTOCOL.md**: Automatic lesson-to-rule conversion
- **Boot Sequence Protocol**: Mitigates hallucination risk by enforcing rules-first behavior
- **AI Self-Completion**: Agents inspect files, logs, diffs, command results, and verification outputs themselves when tool access exists
- **Project Native Language (Language First)**: `AXIARCH.md` sets the agent's user-facing response language — applied to every heading, summary, label, list, table, and bullet — and the owner-facing language for plans, evidence, specs, audits, walkthroughs, and approval requests, unless the latest explicit user instruction overrides it. When that language is Japanese, emitting English headings, summaries, labels, or section titles in the response is a protocol violation (code, APIs, logs, paths excepted)
- **Blueprint First**: Specs required before code for major changes
- **Programming Language Governance**: `axiarch-rules/{lang}/universal/engineering/320_programming_language_governance.md` defines language and framework support tiers, adoption contracts, native quality gates, desktop trust and release boundaries, cross-language contracts, team ownership, polyglot CI, supply-chain evidence, retirement, enterprise and scientific-computing profiles, source-to-device contracts for accelerator/GPU, shader, and eBPF artifacts, evaluator, effective-artifact, permission, lineage, cost, and exit controls for query, semantic, observability, transformation, template, and infrastructure DSLs, source, binary, and behavioral compatibility, consumer matrices, immutable distribution, generated SDK coordination, and organizational ownership for public libraries, SDKs, and packages, plus clean execution, rich-output trust, production jobs, and team handoff for notebooks and literate computational artifacts.
- **React Native Engineering**: `axiarch-rules/{lang}/universal/engineering/420_react_native.md` governs New Architecture, Hermes, Codegen, Swift/Kotlin boundaries, both-OS tests, OTA safety, observability, and enterprise team ownership.
- **Cloud & Application Platform Governance**: `axiarch-rules/{lang}/universal/engineering/520_cloud_application_platforms.md` governs capability-based adoption, shared responsibility, team access, environment isolation, artifact and managed-runtime lifecycles, SDK support tiers and protocol fallbacks, promotion and rollback, workload identity, data recovery, security, observability, FinOps, portability, exit, async-event delivery, local/emulator conformance, provider-managed integrations, multi-service aggregate releases, BaaS capability manifests, trust surfaces, per-capability lifecycles, identity portability, and service-EOL revalidation across Vercel, Supabase, Firebase, Cloudflare, hyperscalers, AWS Amplify, Appwrite, Convex, enterprise, regional, and sovereign clouds, PaaS, and Kubernetes.
- **Microsoft Azure Cloud Governance**: `axiarch-rules/{lang}/universal/engineering/530_azure_cloud.md` governs landing zones, Microsoft Entra, Azure Policy, IaC, managed compute, language and SDK lifecycles, Azure Functions managed, Preview, Custom Handler, worker-model, and hosting-plan support surfaces, releases, networking, Key Vault, data, messaging, observability, reliability, FinOps, enterprise teams, managed conformance, and exit without making a SKU, region, tool, threshold, or organization chart universal.
- **Database Integrity**: Routine DB schema or data changes are version-controlled as migrations or approved runbooks and applied through the agreed pipeline; manual console changes require explicit emergency approval and reconciliation
- **SSOT and Branch Discipline**: Inspect branch and working tree before work; after merge, handoff, or branch exit, sync with the agreed mainline when workflow and permissions allow it, or record why not
- **Human Approval Gate**: No `git add` / stage, `git commit`, `git push`, deploy, release, tag, DB apply, destructive operation, sensitive boundary change, or irreversible action without explicit action-specific human approval
- **Read-Only Delegation Boundary**: Read-only subagent/security-scan fanout requested by the user is not blocked solely for separate subagent permission; stop only before state-changing, production, sensitive, cost, install/auth, or other approval-required actions
- **Existing Behavior Protection**: Preserve working behavior and unrelated user changes; prefer narrow diff-based edits over broad rewrites
- **Current Task State**: `task.md` / `implementation_plan.md` / `walkthrough.md` are current-task Markdown evidence. `axiarch-task-state.sh` preserves root documents, creates session-specific templates in the Project Native Language, and checks shared task records through explicit readiness/completion phases.
- **Native Task State Sync**: Codex uses `update_plan`; Claude Code uses `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet`, with `TodoWrite` only as an older-runtime fallback.

## Quick Start

Distributed Axiarch license and attribution are retained in `axiarch-rules/LICENSE` and `axiarch-rules/NOTICE`; adopter-root notices stay project-owned. Local session evidence is excluded from Git. Use `axiarch-task-state.sh --mode sessions` to list work by its canonical goal while preserving internal session IDs.

Use a reviewed local checkout for unreleased changes. For a published tag, use the installer from that same tag and run it as a file so stdin remains available for choices. The current installer requires its matching Python helpers; older sources without them stop before application. Existing adopters use the Safe Upgrade Wizard rather than reinstalling.

```bash
# Option 1: Interactive setup script (recommended)
bash /path/to/axiarch/init.sh /path/to/your/project

# Option 1b: Pinned stable tag
# Use an explicit template under TMPDIR, defaulting to /tmp if unset or empty
axiarch_bootstrap_dir="$(mktemp -d "${TMPDIR:-/tmp}/axiarch-bootstrap.XXXXXXXX")" &&
curl --fail --silent --show-error --location --proto '=https' --proto-redir '=https' --connect-timeout 15 --max-time 120 \
  https://raw.githubusercontent.com/hiroyuki-miyauchi/axiarch/v1.18.0/init.sh \
  -o "$axiarch_bootstrap_dir/download.part" &&
mv "$axiarch_bootstrap_dir/download.part" "$axiarch_bootstrap_dir/init.sh"
# 取得成功と内容・提供元を確認後に実行 / Run after checking successful download, contents and source
test -n "$axiarch_bootstrap_dir" && AXIARCH_REF=tags/v1.18.0 bash "$axiarch_bootstrap_dir/init.sh" /path/to/your/project

# Option 2: Manual copy
cp AXIARCH.md /path/to/your/project/
cp AGENTS.md /path/to/your/project/
cp -r axiarch-rules /path/to/your/project/
cp -r axiarch-harness /path/to/your/project/

# Optional: safe-upgrade metadata and scripts
cp axiarch-manifest.json /path/to/your/project/
cp -r axiarch-scripts /path/to/your/project/
```

Existing adopter projects can preview a selective upgrade with `bash axiarch-scripts/axiarch-upgrade.sh --to v1.18.0 --dry-run` when pinning the current stable release, or with `--to main --ref heads/main` when intentionally following the latest mainline. Older adopters without the helper can use the private temporary bootstrap procedure in [axiarch-scripts/README.md](axiarch-scripts/README.md#使い方--usage), review the downloaded helper, then run its dry-run preview. A temporary `axiarch_bootstrap_dir` created by `mktemp -d` with an explicit path template uses `TMPDIR` (or `/tmp` if unset or empty) on both macOS and Linux and keeps concurrent downloads separate; only a successful download is renamed to the executable file. The wizard preserves project-owned Blueprint state by default, keeps manifest-listed Axiarch-shared Blueprint rules reviewable for README/INDEX consistency, keeps source-repository-only files skipped by default unless explicitly selected in `--interactive`, and lets ambiguous groups be reviewed interactively with deduplicated action choices. In the Axiarch source repository, Check 15 also verifies the Claude Memory canonical boundary and source release-file Git tracking for current core release files, including `AXIARCH.md`, `axiarch-harness/`, and `axiarch-task-state.sh`; adopter projects skip that source-only tracking check.

## Compatibility

| Agent | Status |
|:------|:-------|
| OpenAI Codex | Unverified primary candidate — native `AGENTS.md` adapter pointing to `AXIARCH.md` + `.codex/hooks.json` integration; unverified in practical operation, no operation guarantee; v1.9.0 adds PostToolUse diff guard, v1.11.0 requires `update_plan` native plan sync where available |
| Claude Code | Unverified primary candidate — native `CLAUDE.md` adapter pointing to `AXIARCH.md` + `.claude/settings.json` hook integration (UserPromptSubmit / PreToolUse / PostToolUse / SessionStart + reminder TTL + Check D task-boundary detection + diff guard); unverified in practical operation, no operation guarantee; v1.11.0 requires Task tools (`TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet`) where available |
| Google Antigravity | ✅ Production-validated primary — native `.agents/rules/prompt_pointer.md` adapter pointing to `AXIARCH.md`; validated through real operational usage |
| Cursor | ⚠️ Extended pointer-only candidate via `.cursor/rules/axiarch.mdc`; unverified and not operation-guaranteed |
| GitHub Copilot | ⚠️ Extended pointer-only candidate via `.github/copilot-instructions.md`; unverified and not operation-guaranteed |
| Windsurf / Aider / Zed | ⚠️ Extended or unverified candidates; not operation-guaranteed |

## Language Support

Available in both languages: Japanese and English (normative counterparts; the project selects its primary language).
All 55 universal rules and core blueprint starter files are available in both languages.
The optional prompt library (`axiarch-prompts/`) is also available in JA/EN.

## License

Apache License 2.0

## Links

- Repository: https://github.com/hiroyuki-miyauchi/axiarch
- [README (Japanese)](README.md#-axiarchアクシアークとは)
- [README (English)](README.md#-what-is-axiarch-ax-ee-ark)
- Issues: https://github.com/hiroyuki-miyauchi/axiarch/issues
- Releases: https://github.com/hiroyuki-miyauchi/axiarch/releases

The record foundation was introduced in v1.17.0; this summary describes the current source. Later Windows and agent-specific fixes are listed separately in [CHANGELOG.md](CHANGELOG.md). Existing adopters receive changes only after an explicit upgrade to the selected published version. Runtime evidence contract: axiarch-harness/{ja,en}/TASK_STATE_PROTOCOL.md. Directly load `axiarch-rules/{lang}/universal/core/300_goal_and_current_state.md` before implementation. D1–D5 distance, M1–M5 maturity and H0–H4 harness classification are separate axes. Session Markdown lives in .axiarch/sessions/{session_id}/; shared state in .axiarch/tasks/{task_id}/state.json. Root legacy evidence is preserved. Python 3 helpers validate structure, readiness and completion separately; health is not proof of semantic understanding or all-operation safety. Upgrade outcomes use per-run result.json, nonzero failure/partial status and last-confirmed version metadata. Release calls the same-commit quality workflow and requires all checks to pass before signed publication. See README runtime/upgrade guarantees for migration and hook coverage.
記録基盤はv1.17.0で導入し、以下は現行ソースの要約。後続のWindows・製品別修正は [CHANGELOG.md](CHANGELOG.md) で区別する。既存導入先への反映には、選択した公開版への明示的な更新が必要。実行契約は axiarch-harness/ja/TASK_STATE_PROTOCOL.md。`axiarch-rules/ja/universal/core/300_goal_and_current_state.md` を実装前に直接ロード。距離D・成熟度M・ハーネスHを区別し、セッション別証跡と共有現在値を分離。旧記録を保持し、構造・準備・完了を別検査する。healthは意味理解や全操作の安全性の証明ではない。更新失敗・保留は非0と結果記録で伝え、releaseは同一commitの品質検査成功を必須とする。