docs: rewrite narrative as AI governance platform, fix version refs, archive evolution

Reposition DevTrail from "documentation helper" to "ISO 42001-aligned
AI governance platform" across all user-facing docs. Lead with regulatory
urgency (EU AI Act Aug 2026) and compliance value proposition.

- README (EN+ES): rewrite Problem/Solution, add compliance automation
  section, update 12 types + 13 commands, remove duplicate standards section
- ADOPTION-GUIDE (EN+ES): add "Why Now?" section, compliance benefits,
  regulated industries in target users
- DEVTRAIL.md: add governance context preamble, C4 Model in standards table
- DOCUMENTATION-POLICY (EN+ES): add governance framework preamble,
  api_spec_path/api_changes fields, bump to v4.0.0
- CLI-REFERENCE (EN+ES): fix all version refs to fw-4.0.0/cli-2.1.0
- CLAUDE.md: fix versions and command list
- Archive evolution/ to docs/archive/evolution/

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: montfort

CLAUDE.md

@@ -12,7 +12,7 @@ devtrail/
 ├── cli/                    # Rust CLI source code
 │   ├── src/
 │   │   ├── main.rs         # Entry point, command routing
-│   │   ├── commands/       # Subcommands: init, update, remove, status, repair, explore, about
+│   │   ├── commands/       # Subcommands: init, update, remove, status, repair, validate, compliance, metrics, audit, explore, about
 │   │   ├── tui/            # Terminal UI for `explore` (ratatui + crossterm)
 │   │   ├── config.rs       # DevTrailConfig, Checksums
 │   │   ├── download.rs     # GitHub API, ZIP downloads
@@ -41,8 +41,8 @@ DevTrail uses **independent versions** for framework and CLI:
 
 | Component | Tag format | Current | Example |
 |-----------|-----------|---------|---------|
-| Framework | `fw-X.Y.Z` | fw-2.1.0 | `fw-2.1.0` |
-| CLI | `cli-X.Y.Z` | cli-1.1.0 | `cli-1.1.0` |
+| Framework | `fw-X.Y.Z` | fw-4.0.0 | `fw-4.0.0` |
+| CLI | `cli-X.Y.Z` | cli-2.1.0 | `cli-2.1.0` |
 
 Follow [semver](https://semver.org/):
 - **Major**: breaking changes

README.md

@@ -2,7 +2,7 @@
 
 # DevTrail
 
-**Documentation Governance for AI-Assisted Software Development**
+**AI Governance Platform for Responsible Software Development**
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
@@ -22,22 +22,19 @@
 
 ## The Problem
 
-As AI coding assistants become integral to software development, a critical gap emerges:
+As AI becomes integral to software development, organizations face three converging pressures:
 
-- **Who made this change?** Was it a developer or an AI assistant?
-- **Why was this decision made?** What alternatives were considered?
-- **Should this have been reviewed?** Was human oversight appropriate?
-- **What's the impact?** How risky is this change?
-
-Without structured documentation, AI-assisted development becomes a black box.
+- **Regulatory compliance**: The EU AI Act becomes mandatory in August 2026. ISO/IEC 42001 is now the international standard for AI governance. Teams need documented evidence.
+- **Governance gap**: No structured way to prove that AI decisions are governed, auditable, and compliant — every undocumented AI change is a liability.
+- **Operational risk**: Who made this change? What alternatives were considered? Was human oversight appropriate? Without answers, AI-assisted development is a black box.
 
 ## The Solution
 
-DevTrail provides a **documentation governance system** that ensures:
+DevTrail is an **ISO 42001-aligned AI governance platform** that ensures every meaningful change — whether by human or AI — is documented, attributed, and auditable.
 
-> **"No significant change without a documented trace."**
+> **"No significant change without a documented trace — and proof of governance."**
 
-Every meaningful change—whether by human or AI—is documented, attributed, and reviewable.
+Teams that adopt DevTrail produce evidence compatible with **ISO/IEC 42001 certification**, **EU AI Act compliance**, and **NIST AI RMF** risk management — while improving development quality and traceability.
 
 ---
 
@@ -99,13 +96,15 @@ Built-in safeguards ensure humans stay in control:
 - **Review triggers**: Low confidence or high risk → mandatory review
 - **Ethical reviews**: Privacy and bias concerns flagged for human decision
 
-### ✅ Validation & CI/CD
+### ✅ Compliance Automation
 
-Automated validation tools:
+Built-in CLI tools for governance:
 
-- **Pre-commit hooks** (Bash) - Validate before commit
-- **PowerShell script** - Windows-friendly validation
-- **GitHub Actions** - PR validation workflow
+- **`devtrail validate`** — 13 validation rules for document correctness
+- **`devtrail compliance`** — Regulatory compliance scoring (EU AI Act, ISO 42001, NIST AI RMF)
+- **`devtrail metrics`** — Governance KPIs, review rates, risk distribution, trends
+- **`devtrail audit`** — Audit trail reports with timeline, traceability maps, and HTML export
+- **Pre-commit hooks** + **GitHub Actions** for CI/CD validation
 
 ---
 
@@ -176,7 +175,7 @@ See [CLI Reference](docs/adopters/CLI-REFERENCE.md) for detailed usage.
 ```bash
 # Download the latest framework release ZIP from GitHub
 # Go to https://github.com/StrangeDaysTech/devtrail/releases
-# and download the latest fw-* release (e.g., fw-2.1.0)
+# and download the latest fw-* release (e.g., fw-4.0.0)
 
 # Extract and copy to your project
 unzip devtrail-fw-*.zip -d your-project/
@@ -230,7 +229,9 @@ Once adopted, DevTrail creates a `.devtrail/` directory in your project for deve
 ├── 07-ai-audit/
 │   ├── agent-logs/          # AILOG documents
 │   ├── decisions/           # AIDEC documents
-│   └── ethical-reviews/     # ETH documents
+│   └── ethical-reviews/     # ETH, DPIA documents
+├── 08-security/             # SEC documents
+├── 09-ai-models/            # MCARD documents
 └── templates/               # Document templates
 ```
 
@@ -356,6 +357,8 @@ DevTrail includes skills for AI agents that enable **active documentation creati
 | `/devtrail-ailog` | Quick AILOG creation | ✅ | ✅ |
 | `/devtrail-aidec` | Quick AIDEC creation | ✅ | ✅ |
 | `/devtrail-adr` | Quick ADR creation | ✅ | ✅ |
+| `/devtrail-sec` | Security Assessment creation | ✅ | ✅ |
+| `/devtrail-mcard` | Model/System Card creation | ✅ | ✅ |
 
 ### Usage Examples
 
@@ -398,7 +401,7 @@ AI agents report documentation status at the end of each task:
 | Status | Meaning |
 |--------|---------|
 | `DevTrail: Created AILOG-...` | Documentation was created |
-| `DevTrail: No documentation required` | Change was minor (<10 lines) |
+| `DevTrail: No documentation required` | Change was minor |
 | `DevTrail: Documentation pending` | May need manual review |
 
 ### Multi-Agent Architecture
@@ -460,17 +463,6 @@ All skill implementations are **functionally identical**—only the format diffe
 
 ---
 
-## Standards Alignment
-
-DevTrail aligns with:
-
-- **ADR** (Architecture Decision Records) - Native support
-- **IEEE 830** - Requirements documentation structure
-- **ISO/IEC 25010** - Quality attributes in ADRs
-- **GDPR** - Privacy impact documentation (ETH)
-- **EU AI Act** - AI transparency and human oversight
-- **NIST AI RMF** - Risk documentation
-
 ---
 
 ## Contributing
@@ -507,7 +499,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 <div align="center">
 
-**DevTrail** — Because every change tells a story.
+**DevTrail** — AI governance, documented.
 
 [⬆ Back to top](#devtrail)
 

dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md

@@ -1,5 +1,16 @@
 # Documentation Policy - DevTrail
 
+## Governance Framework
+
+This policy aligns DevTrail documentation with **ISO/IEC 42001:2023** (vertebral standard for AI Management Systems) and operationalizes:
+
+- **EU AI Act** (effective August 2026) — risk classification, transparency, incident reporting
+- **NIST AI RMF 1.0 + AI 600-1** — AI risk management functions and generative AI profiles
+- **ISO/IEC 23894:2023** — AI risk management framework
+- **GDPR** — data protection and privacy impact assessments
+
+All document types, metadata fields, and governance rules contribute to evidence that satisfies these regulatory frameworks. See Section 8 for the complete standards reference.
+
 ---
 
 ## 1. File Naming Convention
@@ -80,6 +91,8 @@ related:
 | `lines_changed` | Lines changed count (auto-calculable) | In AILOG documents |
 | `files_modified` | List of modified files (auto-calculable) | In AILOG documents |
 | `observability_scope` | OTel instrumentation level: `none \| basic \| full` | When the change involves observability instrumentation |
+| `api_spec_path` | Path to OpenAPI/AsyncAPI specification file | In REQ documents when the requirement involves API interfaces |
+| `api_changes` | List of API endpoints affected | In ADR documents when the decision modifies public APIs |
 
 ### Tags Convention
 
@@ -234,4 +247,4 @@ See also [ADR-2025-01-20-001] for architectural context.
 
 ---
 
-*DevTrail v3.0.0 | [Strange Days Tech](https://strangedays.tech)*
+*DevTrail v4.0.0 | [Strange Days Tech](https://strangedays.tech)*

dist/.devtrail/00-governance/i18n/es/DOCUMENTATION-POLICY.md

@@ -2,6 +2,17 @@
 
 **Idiomas**: [English](../../DOCUMENTATION-POLICY.md) | Español
 
+## Marco de Gobernanza
+
+Esta política alinea la documentación de DevTrail con **ISO/IEC 42001:2023** (estándar vertebral para Sistemas de Gestión de IA) y operacionaliza:
+
+- **EU AI Act** (efectivo agosto 2026) — clasificación de riesgo, transparencia, reporte de incidentes
+- **NIST AI RMF 1.0 + AI 600-1** — funciones de gestión de riesgos de IA y perfiles de IA generativa
+- **ISO/IEC 23894:2023** — marco de gestión de riesgos de IA
+- **GDPR** — evaluaciones de impacto en protección de datos y privacidad
+
+Todos los tipos de documentos, campos de metadatos y reglas de gobernanza contribuyen a evidencia que satisface estos marcos regulatorios. Ver Sección 8 para la referencia completa de estándares.
+
 ---
 
 ## 1. Convención de Nomenclatura de Archivos
@@ -82,6 +93,8 @@ related:
 | `lines_changed` | Conteo de líneas cambiadas (auto-calculable) | En documentos AILOG |
 | `files_modified` | Lista de archivos modificados (auto-calculable) | En documentos AILOG |
 | `observability_scope` | Nivel de instrumentación OTel: `none \| basic \| full` | Cuando el cambio involucra instrumentación de observabilidad |
+| `api_spec_path` | Ruta al archivo de especificación OpenAPI/AsyncAPI | En documentos REQ cuando el requisito involucra interfaces de API |
+| `api_changes` | Lista de endpoints de API afectados | En documentos ADR cuando la decisión modifica APIs públicas |
 
 ### Convención de Tags
 
@@ -236,4 +249,4 @@ Ver también [ADR-2025-01-20-001] para contexto arquitectónico.
 
 ---
 
-*DevTrail v3.0.0 | [Strange Days Tech](https://strangedays.tech)*
+*DevTrail v4.0.0 | [Strange Days Tech](https://strangedays.tech)*

dist/.devtrail/QUICK-REFERENCE.md

@@ -1,6 +1,9 @@
 # DevTrail - Quick Reference
 
 > One-page reference for AI agents and developers.
+>
+> **This is a simplified reference** — see `00-governance/QUICK-REFERENCE.md` for the complete version,
+> or `00-governance/DOCUMENTATION-POLICY.md` for the authoritative source.
 
 ---
 
@@ -157,12 +160,12 @@ Mark `review_required: true` when:
 
 | I just... | Create |
 |-----------|--------|
-| Implemented >10 lines | AILOG |
+| Implemented >20 lines | AILOG |
 | Chose between options | AIDEC |
 | Fixed security issue | AILOG + `risk_level: high` |
 | Found tech debt | TDE |
 | Handled PII data | AILOG + ETH |
 
 ---
 
-*DevTrail | [GitHub](https://github.com/StrangeDaysTech/devtrail) | [Strange Days Tech](https://strangedays.tech)*
+*DevTrail v4.0.0 | [GitHub](https://github.com/StrangeDaysTech/devtrail) | [Strange Days Tech](https://strangedays.tech)*

dist/DEVTRAIL.md

@@ -6,6 +6,18 @@
 
 ---
 
+## Governance Context
+
+These rules operationalize **ISO/IEC 42001:2023** (AI Management System) — DevTrail's vertebral standard. Following them produces documented evidence compatible with:
+
+- **EU AI Act** (Regulation 2024/1689) — risk classification, transparency, incident reporting
+- **NIST AI RMF 1.0 + 600-1** — risk management functions and generative AI risk profiles
+- **GDPR** — data protection impact assessments and privacy safeguards
+
+> See `AI-GOVERNANCE-POLICY.md` for the full ISO 42001 Annex A control mapping.
+
+---
+
 ## 1. Fundamental Principle
 
 > **"No significant change without a documented trace."**
@@ -317,6 +329,7 @@ DevTrail is aligned with the following standards and regulations:
 | **ISO/IEC/IEEE 29119-3:2021** | Software testing documentation | TES |
 | **GDPR** | Data protection and privacy | ETH (Data Privacy) |
 | **OpenTelemetry** | Observability (optional, complementary) | Tag `observabilidad` |
+| **C4 Model** | Architecture visualization in ADR documents | ADR (Mermaid diagrams) |
 
 > **Reference**: See `AI-GOVERNANCE-POLICY.md` for the full ISO 42001 Annex A mapping to DevTrail documents.
 

docs/adopters/ADOPTION-GUIDE.md

@@ -24,37 +24,44 @@
 
 ## What is DevTrail?
 
-DevTrail is a **documentation governance system** designed for software development projects that utilize AI coding assistants. It provides:
+DevTrail is an **ISO 42001-aligned AI governance platform** for software development teams. It provides:
 
-- **Structured documentation** for decisions, actions, and changes
-- **AI agent accountability** through mandatory identification and confidence tracking
-- **Human oversight** via required review workflows for critical changes
-- **Traceability** connecting requirements → design → implementation → testing
+- **12 structured document types** covering the full development and AI lifecycle
+- **Regulatory compliance automation** — EU AI Act, ISO 42001, NIST AI RMF scoring and audit trails
+- **AI agent accountability** through mandatory identification, confidence tracking, and autonomy limits
+- **Human oversight** via required review workflows for critical and high-risk changes
+- **Traceability** connecting requirements → design → implementation → testing → incidents
 
 ### Core Principle
 
-> **"No significant change without a documented trace."**
+> **"No significant change without a documented trace — and proof of governance."**
 
-DevTrail ensures that every meaningful change in your codebase is documented, attributed, and reviewable—whether made by a human developer or an AI assistant.
+DevTrail ensures that every meaningful change — whether by human or AI — is documented, attributed, and auditable. Teams that adopt DevTrail produce evidence compatible with **ISO/IEC 42001 certification** and **EU AI Act compliance**.
+
+### Why Now?
+
+The **EU AI Act becomes mandatory in August 2026**. ISO/IEC 42001 is the international standard for AI Management Systems. Organizations using AI in development need documented governance — not as a nice-to-have, but as a regulatory requirement. DevTrail operationalizes these requirements from day one.
 
 ### What DevTrail is NOT
 
-- ❌ A documentation generator (it provides structure, not content generation)
-- ❌ A replacement for code comments or API docs
-- ❌ A project management tool
-- ❌ A version control system
+- It is not a documentation generator — it provides structure, templates, and governance rules
+- It is not a replacement for code comments or API docs
+- It is not a project management tool or version control system
+- It is not a full ISO 42001 implementation — it produces compatible evidence within its scope
 
 ---
 
 ## Who is it for?
 
 ### Target Users
 
-| User Type | Use Case |
-|-----------|----------|
-| **Solo Developers** | Track your own decisions and AI-assisted changes |
-| **Small Teams** | Maintain consistency across team members and AI tools |
-| **Enterprise Teams** | Audit trails, compliance, governance at scale |
+| User Type | Adoption Drivers |
+|-----------|-----------------|
+| **Teams using AI coding assistants** | Prove governance for regulatory audits and quality assurance |
+| **High-risk AI systems** | EU AI Act mandates documented risk management and transparency |
+| **Organizations seeking ISO 42001** | DevTrail produces certification-ready evidence |
+| **Regulated industries** (finance, healthcare, EU-based) | Regulatory compliance mandatory by August 2026 |
+| **Solo Developers** | Track decisions and AI-assisted changes with structure |
 | **Open Source Maintainers** | Document contribution decisions transparently |
 
 ### Compatible Development Environments
@@ -85,6 +92,16 @@ DevTrail works with any development methodology:
 
 ## Benefits
 
+### For Regulatory Compliance
+
+| Benefit | Description |
+|---------|-------------|
+| **EU AI Act Ready** | Risk classification, incident reporting, and transparency templates built in |
+| **ISO 42001 Compatible** | Documentation structure aligns with certification audit requirements |
+| **NIST AI RMF Mapped** | 12 GenAI risk categories and governance functions explicitly covered |
+| **Audit Trail Complete** | `devtrail audit` generates exportable timeline and traceability reports |
+| **Compliance Scoring** | `devtrail compliance` provides percentage-based regulatory gap analysis |
+
 ### For Development Teams
 
 | Benefit | Description |
@@ -100,17 +117,8 @@ DevTrail works with any development methodology:
 |---------|-------------|
 | **AI Transparency** | Every AI action is logged with confidence levels |
 | **Human Oversight** | Critical decisions require human approval |
-| **Ethical Safeguards** | ETH documents ensure responsible AI use |
-| **Audit Trail** | Complete history of AI contributions |
-
-### For Organizations
-
-| Benefit | Description |
-|---------|-------------|
-| **Compliance Ready** | Documentation structure supports regulatory requirements |
-| **Risk Management** | Risk levels flag high-impact changes |
-| **Knowledge Retention** | Documentation survives personnel changes |
-| **Quality Assurance** | Structured review processes |
+| **Ethical Safeguards** | ETH and DPIA documents ensure responsible AI use |
+| **Governance Metrics** | `devtrail metrics` tracks review rates, risk distribution, and trends |
 
 ---