axiarch

# Axiarch (AX-ee-ark) — Full Specification

> Constitution-Driven AI Agent Governance Framework
> 版数とタグ参照はこのソースの公開対象版を示します。未マージのリリース準備ブランチでは未公開の場合があります。導入前に [公開済み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 | License: Apache 2.0
> Installation examples target v1.18.0; existing adopters must review and apply an upgrade to receive its changes.
> Repository: https://github.com/hiroyuki-miyauchi/axiarch

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, business, AI, and governance work through a multi-layer
constitutional architecture, making consistent output quality easier to maintain
across agents and operator skill levels.

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. Native task/plan tools are used only when available; Markdown evidence does not update their UI by itself.

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

## Core Architecture

Distributions retain `axiarch-rules/LICENSE` and `axiarch-rules/NOTICE` without replacing adopter-root notices. Local task/session evidence is excluded from Git distribution. `axiarch-task-state.sh --mode sessions` displays the canonical goal for each session; internal IDs and resumption paths stay stable.

```
┌─────────────────────────────────────────────────────────────┐
│ Layer 1: Universal (Immutable Constitution)                 │
│ ├─ AXIARCH.md (Canonical Protocol)                          │
│ ├─ AGENTS.md / CLAUDE.md / tool pointers (thin adapters)     │
│ └─ Universal Rules (55 files / Immutable Governance Rules)   │
├─────────────────────────────────────────────────────────────┤
│ Layer 2: Blueprint (Mutable Project State)                  │
│ └─ Project Overview, Feature Specs, Lessons Log             │
├─────────────────────────────────────────────────────────────┤
│ Layer 3: Prompts (Optional Execution Framework)             │
│ └─ Task-specific prompts for audit, QA, upgrade execution   │
├─────────────────────────────────────────────────────────────┤
│ Execution Harness                                           │
│ └─ Harness Engineering: execution, audit, evidence, approval │
├─────────────────────────────────────────────────────────────┤
│ Execution Documents — Per-Task                       ← Gen. │
│ task.md, implementation_plan.md, walkthrough.md             │
├─────────────────────────────────────────────────────────────┤
│ Feedback Loop — Crystallization                      ← Cont.│
│ Lessons → Rules(Layer 2) → Better Lessons                   │
└─────────────────────────────────────────────────────────────┘
```

---

## AXIARCH.md — Canonical Protocol

AXIARCH.md is the canonical protocol governing Axiarch behavior.
AGENTS.md and tool-native files are thin adapters that point to AXIARCH.md.
Do not treat older Protocol 0-9 summaries as active canonical numbering.
The v1.12.0 harness work introduces Harness Engineering as the operational
bridge from rules to task execution. It is not a fourth rule layer; it makes the
three-layer model executable through lifecycle steps, audit verdicts, role
passes, evidence packets, human approval boundaries, and optional delegation.
Read-only subagent delegation is not a Human Approval Gate action by itself.
When the user explicitly requests a deep audit, security scan, exhaustive
review, Codex Security Deep Security Scan, or 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.
The active governance entrypoint is AXIARCH.md, with detailed rule bodies and
execution procedures loaded from the files it references:

- `axiarch-rules/{lang}/LOADING_PROTOCOL.md` for BOOT SEQUENCE and task evidence
- `axiarch-rules/{lang}/CRYSTALLIZATION_PROTOCOL.md` for lesson crystallization
- `axiarch-rules/{lang}/universal/` for project-independent standards
- `axiarch-rules/{lang}/blueprint/` for project-specific state and lessons
- `axiarch-harness/{lang}/EXECUTION_HARNESS_PROTOCOL.md` for task lifecycle
- `axiarch-harness/{lang}/AUDIT_GATE_PROTOCOL.md` for audit verdicts and fix loops
- `axiarch-harness/{lang}/ROLE_PASS_PROTOCOL.md` for main-agent sequential role passes
- `axiarch-harness/{lang}/EVIDENCE_PACKET_PROTOCOL.md` for closeout evidence
- `axiarch-harness/{lang}/HUMAN_APPROVAL_GATE.md` for stage, commit, push, deploy, release, tag, DB, destructive, and sensitive-operation approval boundaries
- `axiarch-harness/{lang}/SUBAGENT_DELEGATION_PROTOCOL.md` for optional delegation and main-agent fallback

Non-negotiable boundaries retained from the former AGENTS protocol:

- Agents self-complete inspections and verification whenever tool access exists.
- Rule loading requires direct file reads; index summaries alone are not enough.
- Project Native Language in 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).
- `task.md`, `implementation_plan.md`, and `walkthrough.md` are current-task evidence.
- 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.
- Agents inspect branch and working tree before work, then sync with the agreed mainline after merge, handoff, or branch exit when workflow and permissions allow it, or record why synchronization did not run.
- Working behavior and unrelated user changes are protected by default.
- Existing files are changed with narrow diffs, not casual full rewrites.
- `git add` / stage, `git commit`, `git push`, deploy, release, tag, DB apply, destructive operation, sensitive boundary change, and irreversible action require explicit action-specific human approval.
- 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.
- Lessons are crystallized only when they actually occurred in the task.

Historical changelog or roadmap entries may mention the earlier AGENTS.md
protocol numbering for older releases. Those entries are release history, not
the active source of truth.

---

## axiarch-rules/{lang}/LOADING_PROTOCOL.md — 5-Step Rule Loading

The AI follows this protocol at the start of every conversation:

### Step 1: Task Classification
Classify the user's instruction into task types: security, architecture,
performance, ui_design, api, i18n, finops, testing, or other.

### Step 2: INDEX-Based File Identification
Read `axiarch-rules/{lang}/INDEX.md` to identify which Universal Rules and Blueprint files
correspond to the task type. Uses a two-class system:
- Class S (Universal): Immutable, project-transcending rules
- Class A (Blueprint): Mutable, project-specific specs and lessons

### Step 3: File Loading (Anti-Laziness Mandate)
Actually open and read each identified file using tools. Reading only
INDEX summaries is strictly prohibited. For large files (1000+ lines),
use table of contents or appendix to selectively load relevant sections.

### Step 4: Post-Load Verification
Record loaded files in task.md. If any applicable file was missed,
stop work and load it before proceeding.

### Step 5: Begin Work
Only after Steps 1-4 are complete may code modifications begin.

---

## axiarch-rules/{lang}/CRYSTALLIZATION_PROTOCOL.md — Lesson Auto-Crystallization

A 6-step process for converting lessons into persistent rules:

1. **Classify**: Determine the lesson's domain (DB/Auth → engineering/,
   Security → security/, Design → design/, etc.)
2. **Dedup Check**: Check whether a similar rule already exists in Universal.
   If covered there, do not duplicate it in Blueprint.
3. **Search**: Check if a domain file already exists in the Blueprint
   folder. If yes, append to it.
4. **Accumulate**: If no domain file exists, temporarily store in
   core/010_project_lessons_log.md with Domain/Target Folder tags.
5. **Threshold Check**: When 3+ lessons of the same domain accumulate,
   create a proper domain file and move lessons there.
6. **Update Index**: Maintain core/010 as an index of unsorted
   lessons + links to separated domain files.

Design philosophy: Co-location principle — lessons are placed in the
same folder as related rule files for maximum context efficiency.

---

## Layer 1: Universal Rules (Immutable Constitution)

All Universal rules are immutable ("Constitution"). 3,000+ standards spanning engineering, product, security, operations, AI, business, QA, FinOps, and governance.

### core/ — Foundation Philosophy (4 files)
- **000_core_mindset.md**: Core behavioral principles. Priority hierarchy
  (Security > UX > Profitability > DX), strict tolerance, Headless First,
  SSOT, band-aid ban, Git/deploy protocols, regression risk reduction.
- **100_governance.md**: Constitutional authority, amendment protocol,
  AI agent authority control, multi-project federation.
- **200_language_protocol.md**: Three-layer language model, code/document
  language conventions, AI communication protocol.
- **300_goal_and_current_state.md**: 10 sections. The boot triad (norms +
  goal + current state) required before work starts, on the premise that
  an agent boots with zero memory; verifiable completion criteria and a
  ban on standalone vague terms, non-goals, the goal restatement gate,
  four-state machine-readable current state (done / in progress / not
  started / discarded) with product-independent container properties and
  a freshness-reconciliation duty, the autonomy-distance scaling law
  (D1-D5), goal drift vs current-state drift, a ban on writing credentials
  or production personal data into shared state (consolidation and access
  control designed together, retention), the duty to stop and report drift
  early with no silent failure, recurrence prevention via crystallization,
  shared state for concurrent work, 17 anti-patterns.

### product/ — Business & Growth (10 files)
- **000_product_strategy.md**: MVP→PMF, monetization, unit economics,
  review/trust systems, tag-based search, interactive engine.
- **100_market_validation.md**: Build Trap avoidance, JTBD, Pain Severity
  Scoring, TAM/SAM/SOM, Mom Test, MVP types, Sean Ellis Test, Retention
  Curve, False PMF Signal protocol, Founder-Market Fit, Regulatory PMF,
  Marketplace PMF, Platform & API PMF, PLG-SLG Hybrid PMF, AI-Native
  Validation, PMF Decay & Erosion. 18 parts, 105+ sections, 120 rules.
- **200_go_to_market.md**: Positioning Canvas, Category Creation, ICP,
  PLG/SLG/MLG/CLG/ELG, Product Hunt protocol, GTM KPI, ABM 3 Tier,
  Signal-Based GTM, Agentic GTM, Competitive Displacement. 15 parts,
  80+ sections, 101 rules.
- **300_revenue_monetization.md**: FinOps, Stripe, point economy, AI token
  economics, dynamic pricing, tax/invoice compliance.
- **400_pricing_strategy.md**: Value-Based Pricing, Van Westendorp PSM,
  Usage-based metrics, Freemium design, Tier design, GBB Framework,
  AI-Native Monetization, Agentic AI Pricing, Price Psychology,
  Enterprise negotiation, Dynamic Pricing, Global multi-currency.
  17 parts, 87 sections, 99 rules, 30 anti-patterns.
- **500_growth_marketing.md**: PLG, SEO/GEO, onboarding, retention,
  ad feed integration, OGP, first-party data, KPI framework.
- **600_brand_strategy.md**: Golden Circle, Brand Pyramid, Design Tokens,
  Voice/Tone, copywriting, crisis response. 8 parts, 30 sections.
- **700_appstore_compliance.md**: Apple/Google guidelines, IAP, privacy
  manifests, ASO, pre-submission checklist.
- **800_internationalization.md**: i18n/L10n, Unicode, CLDR, RTL,
  translation workflows, regional compliance.
- **900_fundraising_ir.md**: Default Alive philosophy, stage benchmarks,
  pitch deck standard, term sheets, Data Room, investor reports.
  8 parts, 32 sections.

### design/ — Design & UX (1 file)
- **000_design_ux.md**: 25-part expanded edition (v3.0). Primary Directive:
  Consistency > Accessibility > Delight > Aesthetics > Dev Speed. W3C DTCG
  2025.10 Design Tokens, WCAG 2.2 AA + WCAG 3.0 forward compatibility (APCA),
  Dark Pattern ban (FTC/DSA/EU DFA), Agentic AI UX patterns, Calm UI,
  Voice UI, Design System as a Product, Design FinOps, 35 anti-patterns.

### engineering/ — Technical Implementation (18 files)
- **000_engineering_standards.md**: Engineering standards. 22 parts,
  141 sections. Code quality, infrastructure, DevSecOps, tech debt,
  AI-first development, Green Coding, bug-reduction policy, Git protocols,
  quality protocols, advanced architecture (Trinity DTO, CQRS, Feature
  Flag Lifecycle).
- **100_api_integration.md**: RESTful design, versioning, rate limiting,
  error handling, CORS governance, API gateway metering.
- **200_supabase_architecture.md**: 60 sections, 200+ rules. DB design,
  RLS, Auth, Storage, Migration, Edge Functions, Realtime, pgvector,
  multi-tenancy, operational maturity model, and capability-specific
  official/community client-library support surfaces distinct from execution
  runtimes.
- **300_web_frontend.md**: Next.js/React/TypeScript. 49 parts, 300
  sections. App Router, Server/Client boundary, CSS architecture,
  React 19, forms, state management, performance, SEO/GEO, accessibility,
  testing, deployment, modern Web APIs, AI integration, 5-level maturity.
- **310_headless_cms.md**: 80 parts, 160 sections, 131 rules. CMS
  philosophy, content modeling, rendering, CDN, publishing workflows,
  AI-Ready Content, Agentic CMS, multi-tenant, 40 anti-patterns.
- **320_programming_language_governance.md**: 19 sections, 86 rules.
  Language portfolio tiers and adoption contracts across frontend, backend,
  mobile, desktop and framework lifecycles, enterprise platforms, long-lived
  COBOL/PL/I and related assets, data/AI and scientific computing,
  infrastructure, systems, accelerator/GPU,
  shaders, eBPF, smart contracts, and hardware; native toolchains, Golden Paths,
  polyglot CI, cross-language contracts, public library and SDK source, binary,
  and behavioral compatibility, consumer matrices, immutable package
  distribution, generated SDK coordination, organizational ownership,
  SBOM/provenance, ownership, retirement; notebook and literate computational
  artifact profiles, clean execution, rich-output trust boundaries, production
  job operating contracts, and managed-workspace team handoff.
- **400_mobile_flutter.md**: 55 parts, 265 sections. Flutter 3.41+,
  Riverpod 3.0+, Impeller, Clean Architecture, offline-first, security
  (OWASP MASVS), Passkeys/FIDO2, 50 anti-patterns.
- **410_native_platforms.md**: 40 parts and 186 sections covering Kotlin 2.4,
  Swift 6.3, Android and Apple platforms, KMP, Compose, SwiftUI, typed
  cross-platform boundaries, testing, release, and supply chain. Official
  platform constraints stay normative; tools, thresholds, and team shapes are
  replaceable examples or Blueprint parameters.
- **420_react_native.md**: 17 sections, 52 rules. Framework-managed, bare,
  and brownfield profiles; New Architecture, Hermes, Codegen, typed native
  boundaries, both-OS tests, release performance, secure OTA, supply-chain
  evidence, observability, a scale-appropriate Mobile Platform function, and
  upgrade governance without mandating one vendor or organization chart.
- **500_firebase_gcp.md**: 57 sections, 175 rules. Cloud Run, Firestore,
  Auth, FCM, Genkit, Vertex AI, Zero Trust, FinOps, Terraform, 35
  anti-patterns, and distinct client SDK, Admin SDK, framework binding,
  managed runtime, buildpack, and container support surfaces.
- **510_aws_cloud.md**: 155 sections, 240+ rules. Well-Architected
  Framework, all major AWS services, 20 anti-patterns.
- **520_cloud_application_platforms.md**: 22 sections, 89 rules.
  Capability-based selection and shared responsibility across Vercel,
  Supabase, Firebase, Cloudflare, hyperscalers, enterprise, regional and
  sovereign clouds, PaaS, and Kubernetes;
  environment isolation, release/rollback, identity, data, SDK support tiers,
  feature parity, generated clients, protocol fallbacks, security,
  observability, FinOps, portability, exit, team platform engineering, and
  vendor-neutral async-event delivery, idempotency, ordering, retry, DLQ,
  quarantine, replay, local/emulator fidelity matrices, managed-environment
  conformance, and provider-managed integration and extension lifecycle
  contracts, plus multi-service service graphs, release topologies, aggregate
  evidence, route-conflict checks, and partial-deployment recovery.
- **530_azure_cloud.md**: 21 sections, 85 rules. Microsoft Azure provider
  profile for landing zones, Microsoft Entra, RBAC and PIM, Azure Policy, IaC,
  managed compute, language and SDK lifecycles, release slots and revisions,
  Azure Functions managed, Preview, Custom Handler, worker-model, and
  hosting-plan support surfaces, networking, Key Vault, data and migration, messaging, Azure Monitor,
  reliability, FinOps, enterprise Platform Engineering, managed conformance,
  supply-chain evidence, exit, and decommissioning.
- **600_git_workflow.md**: 10 parts, 45 rules. Trunk-based development,
  Conventional Commits, branch/worktree hygiene, branch protection,
  tags/releases, secret scanning, anti-pattern catalog.
- **700_batch_backfill_operations.md**: 8 sections, 57 rules. Job-summary
  & failure-accounting contract (three-valued outcome, no silent skips,
  per-item failure capture + DLQ, canonical summary line, OTel
  error.type), backfill discipline (idempotency, checkpoint/resume,
  chunking + backpressure, mandatory dry-run, four-phase migration,
  shadow read, independent verification, kill switch), job-specific
  test obligations, 20 anti-patterns.
- **710_data_reconciliation.md**: 10 sections, 51 rules. Steady-state
  consistency verification for conservation quantities (money, inventory,
  points, usage billing): mandatory invariants + invariant catalog,
  steady-state reconciliation jobs, Stripe-Ledger-style metrics
  (Clearing/Timeliness/Completeness) + explainability % SLO, append-only
  / reversing entries, drift detection, 15 anti-patterns.
- **730_caching_discipline.md**: 11 sections, 46 rules. Language-agnostic
  caching: staleness contracts, soft/hard dual TTL + fail-open/closed
  choice, TTL jitter, single-flight stampede prevention, multi-layer
  invalidation ordering, schema-versioned keys, RFC 5861 SWR/SIE,
  total-loss resilience, authz/PII caching boundaries, 15 anti-patterns.
- **740_data_contracts.md**: 11 sections, 42 rules. Producer/consumer
  contracts for cross-boundary data (events, tables, topics, files):
  contracts as code + CI, ODCS v3.1.0 (emerging), compatibility modes
  (default BACKWARD), mandatory schema registry, three-phase breaking
  changes, Tolerant Reader, PII classification tags, 15 anti-patterns.

### ai/ — AI & Data (2 files)
- **000_ai_engineering.md**: 48 parts, 150+ sections. AI UX patterns,
  ethics (EU AI Act), RAG (GraphRAG), Agentic AI (L1-L5, MCP/A2A),
  guardrails, AI FinOps, LLMOps, 20 anti-patterns.
- **100_data_analytics.md**: 60 parts, 206 sections. Event taxonomy,
  A/B testing, Privacy Sandbox, OpenTelemetry, AIOps 2.0, LLM
  observability, 25 anti-patterns.

### operations/ — Operations & SRE (9 files)
- **000_internal_tools.md**: 50 parts, 231 sections. Admin dashboard,
  RBAC/ABAC, audit logging, AI integration, FinOps, 20 anti-patterns.
- **100_sales_bizdev.md**: Challenger Sale, MEDDIC, Sales Funnel,
  Partner evaluation. 10 parts, 38 sections.
- **200_hr_organization.md**: Talent Density, Bar Raiser, OKR, Team
  Topologies, Remote-First. 9 parts, 34 sections.
- **300_customer_experience.md**: AI agent strategy, omnichannel,
  Customer Health Score, churn-risk reduction. 40 parts.
- **400_site_reliability.md**: SLI/SLO/SLA, chaos engineering,
  Platform Engineering, AIOps. 55 parts, 166 sections.
- **500_incident_response.md**: ISO 22301/NIST CSF 2.0, BIA, crisis
  communication, BCP/DR, blameless postmortem. 31 parts.
- **600_cloud_finops.md**: FinOps Foundation 2026, FOCUS v1.3, AI/ML
  FinOps, Agentic AI FinOps, K8s FinOps, GreenOps. 25 parts, 57 sections.
- **650_capacity_planning.md**: 10 sections. Scale-cliff ledger (DB
  connections, pools, hot partitions, API rate limits, cloud quotas),
  measured capacity calibration / breaking-point tests, numeric headroom
  (N+1/N+2), 4 load-test scenarios, autoscaling caps, demand forecasting,
  graceful degradation, 15 anti-patterns.
- **700_partnership_ecosystem.md**: Partnership Maturity Model,
  Ecosystem Flywheel, Developer Portal. 9 parts, 34 sections.

### security/ — Security & Legal (10 files)
- **000_security_privacy.md**: Zero Trust (NIST 800-207), FIDO2,
  OWASP Top 10 2025, AI/LLM security (OWASP LLM Top 10), supply
  chain (SBOM/SLSA), PQC readiness. 22 sections. (Authentication §4/§5/§6
  are an overview; deep-dives are 400/410/420/430/440.)
- **100_data_governance.md**: GDPR/Global Privacy Laws/CCPA/EU AI Act, consent
  management, RegTech, quantum crypto agility. 45 sections.
- **200_oss_compliance.md**: License classification, SBOM (CycloneDX/
  SPDX), SLSA v1.2 Build and Source Tracks, SCA tools. 63 sections, 299 rules.
- **300_ip_due_diligence.md**: Patents, trade secrets, AI-generated IP,
  exit strategy, DD operations. 50 sections.
- **400_authentication_and_passkeys.md**: Phishing-resistant-first,
  passkeys/WebAuthn (L2 REC / L3 CR), FIDO2, MFA/2FA (TOTP, Number
  Matching, hardware keys), NIST SP 800-63B/-4 password policy,
  credential lifecycle, account recovery, CIAM vs Workforce. 13 sections.
- **410_federated_identity_and_oauth.md**: OAuth 2.1 (IETF draft; baseline
  RFC 9700), PKCE/PAR/RAR/DPoP, OIDC + ID-token validation, social login
  (Google/Apple/MS/GitHub), SSO (SAML/OIDC), refresh rotation + reuse
  detection, consent/device-code phishing, FedCM. 22 sections.
- **420_step_up_auth_and_sensitive_operations.md**: Assurance (acr/amr,
  AAL), step-up/re-auth, risk-based/adaptive (CAEP/SSF), OTP/magic links,
  transaction signing (WYSIWYS), sensitive-op gating, sessions, breach
  Kill Switch, enumeration prevention. 12 parts.
- **430_authorization_and_access_control.md**: Fine-grained authZ — PDP/PEP,
  deny-by-default, RBAC/ABAC/ReBAC, Google Zanzibar (OpenFGA/SpiceDB),
  Policy as Code (Cedar/OPA), decision logs, multi-tenancy/RLS. 13 sections.
- **440_workload_and_agent_identity.md**: Non-human/workload identity
  (SPIFFE/SPIRE, WIF, M2M client credentials, Zero Standing Privilege)
  and AI-agent auth/delegation (Tier-0, OBO via RFC 8693 Token Exchange,
  delegation-chain limits, MCP/XAA — emerging). 18 sections.
- **450_mcp_security.md**: MCP (Model Context Protocol) security, consumer
  + builder sides (spec 2025-11-25). OAuth 2.1 Resource Server, RFC 9728
  metadata, RFC 8707 audience binding, token-passthrough prohibition
  (Confused Deputy), Origin/DNS-rebinding defense, tool-definition hash
  pinning (rug-pull/tool-poisoning detection), human-in-the-loop approval,
  execution isolation, untrusted-tool-output handling. 18 sections.

### quality/ — Testing & QA (1 file)
- **000_qa_testing.md**: Test philosophy, 10+ test types, security
  testing, AI-driven testing, 5-level maturity model. 40 sections.

---

## Layer 2: Blueprint Templates (Mutable Project State)

Mutable templates for each project:
- **core/000_project_overview.md**: Project tech stack, architecture, goals
- **core/010_project_lessons_log.md**: Central lessons index with auto-separation
- **core/020_governance_rules.md**: Crystallized governance lessons for canonical entrypoint, Language First non-degradation, and read-only delegation boundaries
- **core/998_feature_spec_template.md**: Feature spec with Given/When/Then
  acceptance criteria (Blueprint First core)
- **core/999_project_specific_template.md**: Custom project rules

---

## Layer 3: Prompts (Optional Execution Framework)

Optional reusable prompt templates organized by role:

### develop/ — Development & Execution (5 prompts)
- **feature_development.md**: New feature implementation, improvement,
  bug fixing, and compliance auditing
- **refactoring_audit.md**: Non-destructive refactoring — structure,
  type safety, DRY without behavior changes
- **push_execute.md**: Quality gate, DB integrity, branch strategy,
  and atomic push execution
- **ci_fix.md**: CI/CD failure reproduction, root cause analysis, fix,
  and rule feedback
- **safe_upgrade_execute.md**: Manifest-based selective Axiarch upgrade
  execution for existing adopter projects, including source-only default skip
  and explicit interactive selection boundaries plus deduplicated action choices

### audit/ — Quality & Integrity Auditing (5 prompts)
- **fullstack_qa_audit.md**: 6-Pillar operational quality review
  with priority reporting and ROI proposals
- **api_architecture_audit.md**: API design, DTO, Zero Trust,
  omnichannel readiness
- **data_integrity_audit.md**: JSON dump detection, Hybrid Sync,
  Split Brain elimination, facade detection
- **system_integrity_audit.md**: Type safety, API/DB sync, facade
  detection, data monetization readiness
- **deep_optimization_audit.md**: Media/LCP/SSR gap root cause
  detection and full-system integrity

### govern/ — Compliance & Governance (5 prompts)
- **compliance_inspector_audit.md**: 8 Major Constitutional Violations
  framework deep compliance audit
- **constitution_compliance_audit.md**: 7 Major Violations scan
- **governance_auditor.md**: 8-Pillar holistic governance audit
- **blueprint_governance_audit.md**: Crystallize development insights
  into Blueprint rules
- **localization_audit.md**: native UI coverage review, LTV, AI/GEO, legal
  localization audit

### operate/ — Incident Response & Onboarding (2 prompts)
- **onboarding_audit.md**: Codebase deep understanding, architecture,
  landmines, and first actions
- **incident_response.md**: SRE-focused triage, 5 Whys RCA, emergency
  fix, postmortem, recurrence-risk reduction

---

## Agent Compatibility

| Agent | Status | Native Config |
|:------|:-------|:-------------|
| OpenAI Codex | Unverified primary candidate; unverified in practical operation, no operation guarantee | `AGENTS.md` adapter → `AXIARCH.md` + `.codex/hooks.json` (4 hooks including PostToolUse diff guard); use `update_plan` for native plan state |
| Claude Code | Unverified primary candidate; unverified in practical operation, no operation guarantee | `CLAUDE.md` adapter → `AXIARCH.md` + `.claude/settings.json` (4 hooks: SessionStart / UserPromptSubmit / PreToolUse / PostToolUse); use Task tools (`TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet`) when available |
| Google Antigravity | ✅ Production-validated primary | `.agents/rules/prompt_pointer.md` adapter → `AXIARCH.md` |
| Cursor | ⚠️ Extended pointer-only candidate; unverified, no operation guarantee | `.cursor/rules/axiarch.mdc` adapter → `AXIARCH.md` |
| GitHub Copilot | ⚠️ Extended pointer-only candidate; unverified, no operation guarantee | `.github/copilot-instructions.md` adapter → `AXIARCH.md` |
| Windsurf | ⚠️ Extended pointer-only candidate; unverified, no operation guarantee | `.windsurfrules` adapter → `AXIARCH.md` |
| Aider / Zed | ⚠️ Unverified; no operation guarantee | Reads `AXIARCH.md` directly or through an adapter |

---

## Quick Start

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 (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/
# Optional: cp -r axiarch-prompts /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.

## 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.
The init.sh setup script handles language and agent selection; deleting unused
language directories is optional when a project is fixed to one language.

## Links

- Repository: https://github.com/hiroyuki-miyauchi/axiarch
- [Summary (llms.txt)](llms.txt)
- [README (Japanese)](README.md#-axiarchアクシアークとは)
- [README (English)](README.md#-what-is-axiarch-ax-ee-ark)
- Issues: https://github.com/hiroyuki-miyauchi/axiarch/issues
- Discussions: https://github.com/hiroyuki-miyauchi/axiarch/discussions
- 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の品質検査成功を必須とする。