diff --git a/CHANGELOG.md b/CHANGELOG.md index 6ed1af5..39e8a68 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,36 @@ and this project uses [independent versioning](README.md#versioning) for Framewo --- +## Framework 4.5.0 — repositioning: engineering-discipline-first, compliance as side effect (EN canonical docs) + +This release does not add features; it realigns the canonical English-language positioning to match how DevTrail is actually used and the explicit hierarchy of `Propuesta/devtrail-design-principles.md`. The previous framing led with compliance ("AI Governance Platform for Responsible Software Development") which inverted Principle #4 — *regulatory compliance is a side effect, not the product* — and Principle #2 — *the primary user is the senior engineer orchestrating agents, not the compliance officer*. This release restates the product in those terms. + +Scope of this release is **EN canonical only**. Spanish and Simplified Chinese translations are deferred to a follow-up release (`fw-4.5.x`) so the EN positioning ships in a focused, reviewable PR; until then, ES and zh-CN docs continue to reflect the prior framing. + +### Changed (Framework) + +- **`README.md`** (EN) rewritten: + - New headline: *"The cognitive discipline your AI-assisted projects need"* (was: *"AI Governance Platform for Responsible Software Development"*). + - **`## The Problem`** reframed around how AI agents lose coherence over many turns and accumulate hidden technical debt — not around regulatory pressure. + - **`## The Solution`** reframed as a *framework + CLI that externalizes the cognitive discipline of senior software engineering work* into versioned files alongside the code. Compliance is presented as the side effect when the discipline is real. + - **New `## Who is DevTrail for`** persona section: primary user is the senior engineer orchestrating agents; tech leads, compliance officers, and adopters in regulated environments are explicit secondary audiences (never at the primary user's expense). Anti-positioning bullets enumerate what DevTrail is *not* trying to be. + - **New `## Design Principles`** section: the 12 principles summarized one-line each, with a link to the full polished document at `Propuesta/devtrail-design-principles.md` for the empirically-annotated v0.2.2 version. + - **New `## Honest Limits`** top-level section operationalizing Principle #10 (*honesty about what the tool does not do*). + - **`## Compliance`** is now a single dedicated section (the previous *Standards Alignment* + *China Regulatory Compliance* fragments are unified) with an opening paragraph that frames compliance as a *consequence of doing the engineering work well*, not as the product. + - The Features subsection *Compliance Automation* is renamed to *CLI Tooling* and now leads with `devtrail charter` as the unit of agent execution. +- **`dist/DEVTRAIL.md`**: opening *Governance Context* section replaced with *Why these rules exist* — leads with externalizing senior-engineering cognitive discipline; lists the regulatory frameworks as evidence the artifacts align with, not as the goal. The *Fundamental Principle* is broadened from *"No significant change without a documented trace"* to *"No significant change without a documented trace — and a constrained decision space for the agent."* +- **`dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md`**: opening *Governance Framework* section replaced with *Why this policy exists*. Same engineering-first framing as `DEVTRAIL.md`. The standards list is preserved verbatim and remains authoritative; only the positioning around it changes. +- **`cli/Cargo.toml`** description updated from *"CLI tool for DevTrail - Documentation Governance for AI-Assisted Development"* to *"CLI for DevTrail — the cognitive discipline your AI-assisted projects need"* (visible on crates.io). +- **`Propuesta/devtrail-design-principles.md`** polished (v0.2.1 → v0.2.2): internal Sentinel-specific references generalized for public readability (PR #70). Now linked publicly from `README.md` and `DEVTRAIL.md`. + +### Notes + +- **No schema changes.** No template changes. No CLI behavior changes. Adopters who pick up fw-4.5.0 via `devtrail update-framework` get the new English `DEVTRAIL.md` + `00-governance/` files; their project-level `.devtrail/config.yml` and existing documents are unaffected. +- **i18n parity gap is intentional and time-bounded.** The Spanish and Simplified Chinese governance docs (`i18n/es/`, `i18n/zh-CN/`) and the `docs/i18n/es/`, `docs/i18n/zh-CN/` README + CLI-REFERENCE retain their fw-4.4.2 language and version footer until the i18n catch-up release. Their `*DevTrail v4.4.2*` footers are correct for their content; only the EN canonical surface advances to v4.5.0 in this release. +- **Why minor and not patch.** This release changes the *meaning* the canonical docs project to readers — the headline of the README, the opening of `DEVTRAIL.md`, the opening of `DOCUMENTATION-POLICY.md`. By Keep a Changelog conventions and DevTrail's own semver discipline (CLAUDE.md), repositioning of canonical surface is *changed* (minor), not *fixed* (patch). Schema and template stability is unaffected. + +--- + ## CLI 3.6.1 — `devtrail charter new` "Next steps" output renumbers correctly when origin is set ### Fixed (CLI) diff --git a/README.md b/README.md index f3a993d..48b050c 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # DevTrail -**AI Governance Platform for Responsible Software Development** +**The cognitive discipline your AI-assisted projects need** [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/StrangeDaysTech/devtrail/blob/main/LICENSE) [![Crates.io](https://img.shields.io/crates/v/devtrail-cli.svg)](https://crates.io/crates/devtrail-cli) @@ -11,10 +11,11 @@ [![Strange Days Tech](https://img.shields.io/badge/by-Strange_Days_Tech-purple.svg)](https://strangedays.tech) [Getting Started](#getting-started) • +[Who is it for](#who-is-devtrail-for) • +[Design Principles](#design-principles) • [Features](#features) • -[China Compliance 中国合规](#china-regulatory-compliance--中国合规) • -[Documentation](#documentation) • -[Contributing](#contributing) +[Compliance](#compliance) • +[Documentation](#documentation) **Languages**: English | [Español](https://github.com/StrangeDaysTech/devtrail/blob/main/docs/i18n/es/README.md) | [简体中文](https://github.com/StrangeDaysTech/devtrail/blob/main/docs/i18n/zh-CN/README.md) @@ -24,19 +25,54 @@ ## The Problem -As AI becomes integral to software development, organizations face three converging pressures: +AI agents make code fast. They don't make code coherent. After enough turns, an agent loses the thread: it re-introduces patterns the team rejected, accumulates hidden technical debt, and produces work that compiles but doesn't fit the system's grain. The faster the agent, the harder this debt is to see — until a regression, an incident, or a refactor surfaces it. -- **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 senior engineers orchestrating these agents don't need *more* agent autonomy. They need the opposite: a way to externalize scope, decisions and risks at a cadence the agent can be held to — so that the agent executes against constraints instead of inventing its own. ## The Solution -DevTrail is an **ISO 42001-aligned AI governance platform** that ensures every meaningful change — whether by human or AI — is documented, attributed, and auditable. +DevTrail is a **framework + CLI** that externalizes the cognitive discipline of senior software engineering work — explicit scope, declared decisions, named risks, recorded alternatives, audited trails — into versioned files that live alongside the code. -> **"No significant change without a documented trace — and proof of governance."** +> **"No significant change without a documented trace — and a constrained decision space for the agent."** -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. +The discipline produces, as a side effect, evidence compatible with **ISO/IEC 42001**, **EU AI Act**, **NIST AI RMF**, and (opt-in) the Chinese AI/data regulatory stack. But the goal is engineering quality first; compliance is what falls out when the discipline is real. + +--- + +## Who is DevTrail for + +DevTrail's primary user is the **senior engineer orchestrating AI agents on a non-trivial system** — someone with strong technical judgment who uses agents to take on work they couldn't realistically do alone, and who needs externalized cognitive discipline so the agent doesn't introduce systemic chaos. + +If that describes you, DevTrail's flows, defaults, and language are tuned for you. + +DevTrail also serves three secondary audiences, on top of that base — never at its expense: + +- **Tech leads and architects** standardizing how their team works with AI assistants. +- **Compliance officers and auditors** who need evidence of governed AI development (ISO 42001, EU AI Act, NIST AI RMF, PIPL, TC260, …). +- **Adopters in regulated environments** (finance, health, public sector, China) who need traceability built into the workflow rather than reconstructed after the fact. + +DevTrail is **not** trying to be: an LLM gateway, a model evaluator, a "10× your code" productivity skin, or a substitute for engineering judgment. See [Honest Limits](#honest-limits) below. + +--- + +## Design Principles + +DevTrail's product decisions are anchored in twelve explicit principles. They are ordered by hierarchy: when two conflict, the earlier one wins. + +1. **The tool serves the craft, not the product.** The metric is whether the engineer produces work they're proud of — not adoption, retention, or revenue. +2. **The primary user is the senior engineer orchestrating agents.** Not the VP, not the CISO, not the compliance officer. +3. **Strict open source, no asterisks in the core.** Framework, CLI and TUI are MIT, with no capped features pushing toward a paid tier. +4. **Regulatory compliance is a side effect, not the product.** ISO 42001, EU AI Act, NIST AI RMF are useful frames; they are not the goal. +5. **Schema-driven before feature-driven.** Central entities (Stage Closure Bundle, Charter, Document) are versioned schemas first, features second. +6. **Cognitive discipline over raw productivity.** DevTrail competes against the chaos that fast AI code generates in serious projects — not against the speed itself. +7. **Local-first, Cloud as amplifier.** The CLI works fully offline. Cloud may add value (cross-repo aggregation, signed evidence) but never gates the core. +8. **Project memory lives in the repo, not in an external database.** AILOGs, ADRs, AIDECs, Charters and bundles are versioned files alongside the code, in markdown + JSON Schema. +9. **Simplicity over capability.** When two designs meet the goal, the simpler one wins. Patterns crystallize after they're validated in real projects, not before. +10. **Honesty about what the tool does not do.** No model evaluation, no LLM gateway, no automatic compliance certification, no replacement for engineering judgment. +11. **The community takes care of the tool, not the other way around.** Contributions and feedback are taken seriously without becoming a democracy. +12. **The product's velocity is the velocity of learning.** No premature crystallization; schemas marked `v0` until validated against a second domain. + +The full document, with empirical annotations from validation cycles, lives in [`Propuesta/devtrail-design-principles.md`](https://github.com/StrangeDaysTech/devtrail/blob/main/Propuesta/devtrail-design-principles.md). --- @@ -65,31 +101,7 @@ Sixteen document types covering the full development lifecycle (twelve core + fo | **TC260RA** ⚪ | TC260 Risk Assessment (China) | Five-level risk grading per AI Safety Framework v2.0 | | **AILABEL** ⚪ | GB 45438 Content Labeling Plan (China) | Explicit + implicit labeling for generative AI | -⚪ Available only when `regional_scope: china` is enabled in `.devtrail/config.yml` — see [China Regulatory Compliance](#china-regulatory-compliance--中国合规) below. - -### 📐 Standards Alignment - -| Standard | DevTrail Integration | -|----------|---------------------| -| **ISO/IEC 42001:2023** | Vertebral standard — AI Management System governance | -| **EU AI Act** | Risk classification, incident reporting, transparency | -| **NIST AI RMF / 600-1** | 12 GenAI risk categories in ETH/AILOG | -| **ISO/IEC 25010:2023** | Software quality model in REQ/ADR | -| **ISO/IEC/IEEE 29148:2018** | Requirements engineering in REQ | -| **ISO/IEC/IEEE 29119-3:2021** | Test documentation in TES | -| **GDPR** | Data protection in ETH/DPIA | -| **OpenTelemetry** | Observability (optional) | - -#### China Regulatory Coverage — opt-in via `regional_scope: china` - -| Standard | DevTrail Integration | -|----------|---------------------| -| **TC260 AI Safety Governance Framework v2.0** | Five-level risk grading (TC260RA) | -| **PIPL — Personal Information Protection Law** | Personal Information Protection Impact Assessment (PIPIA), retention ≥ 3 years | -| **GB 45438-2025** *(mandatory)* | AI-generated content labeling — explicit + implicit (AILABEL) | -| **CAC Algorithm Filing** | Algorithm registration, dual filing process (CACFILE) | -| **GB/T 45652-2025** | Pre-training & fine-tuning data security (SBOM/MCARD) | -| **CSL 2026** | Cybersecurity incident reporting (1h / 4h+72h+30d windows) on INC | +⚪ Available only when `regional_scope: china` is enabled in `.devtrail/config.yml` — see [Compliance](#compliance) below. ### 🤖 AI Agent Support @@ -115,24 +127,64 @@ 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 -### ✅ Compliance Automation +### ✅ CLI Tooling -Built-in CLI tools for governance: +Built-in commands that turn the discipline into actionable feedback: -- **`devtrail validate`** — 25+ validation rules for document correctness (12 China-specific are scope-aware) -- **`devtrail compliance`** — Regulatory compliance scoring (EU AI Act, ISO 42001, NIST AI RMF; six Chinese frameworks opt-in via `--region china`) +- **`devtrail charter `** — Bounded units of work declared ex-ante, audited ex-post (the unit of agent execution) +- **`devtrail validate`** — 25+ validation rules for document correctness (12 China-specific are scope-aware); `--include-charters` extends to `docs/charters/` - **`devtrail metrics`** — Governance KPIs, review rates, risk distribution, trends - **`devtrail analyze`** — Code complexity analysis (cognitive + cyclomatic) powered by [arborist-metrics](https://github.com/StrangeDaysTech/arborist), our open-source Rust library for multi-language code metrics - **`devtrail audit`** — Audit trail reports with timeline, traceability maps, and HTML export +- **`devtrail compliance`** — Regulatory compliance scoring as a side effect of the documented work (EU AI Act, ISO 42001, NIST AI RMF; six Chinese frameworks opt-in via `--region china`) +- **`devtrail explore`** — Interactive TUI for navigating the project's documentation graph - **Pre-commit hooks** + **GitHub Actions** for CI/CD validation --- -## China Regulatory Compliance — 中国合规 +## Honest Limits + +DevTrail does **not**: + +- evaluate, benchmark, or rank LLMs; +- act as an LLM gateway or routing layer; +- prevent hallucinations or guarantee agent correctness; +- automatically certify regulatory compliance — it produces evidence, not certifications; +- replace the judgment of a senior engineer. + +If your problem is one of those, DevTrail is not the tool. + +--- + +## Compliance + +The discipline DevTrail externalizes — explicit scope, declared decisions, named risks, recorded alternatives — produces, as a side effect, evidence that maps cleanly onto the major AI governance frameworks. Compliance is therefore positioned as a *consequence of doing the engineering work well*, not as the product itself (Principle #4). + +### Standards Alignment + +| Standard | DevTrail Integration | +|----------|---------------------| +| **ISO/IEC 42001:2023** | Vertebral standard — AI Management System governance | +| **EU AI Act** | Risk classification, incident reporting, transparency | +| **NIST AI RMF / 600-1** | 12 GenAI risk categories in ETH/AILOG | +| **ISO/IEC 25010:2023** | Software quality model in REQ/ADR | +| **ISO/IEC/IEEE 29148:2018** | Requirements engineering in REQ | +| **ISO/IEC/IEEE 29119-3:2021** | Test documentation in TES | +| **GDPR** | Data protection in ETH/DPIA | +| **OpenTelemetry** | Observability (optional) | + +### China Regulatory Coverage — opt-in via `regional_scope: china` -DevTrail covers six Chinese AI / data regulations as an **opt-in** regional scope: **TC260 AI Safety Governance Framework v2.0**, **PIPL** (Personal Information Protection Law), **GB 45438-2025** (mandatory AI content labeling), **CAC Algorithm Filing**, **GB/T 45652-2025**, and the **CSL 2026** incident-reporting amendments. Activate by adding `regional_scope: china` to `.devtrail/config.yml`; projects without it are unaffected. +| Standard | DevTrail Integration | +|----------|---------------------| +| **TC260 AI Safety Governance Framework v2.0** | Five-level risk grading (TC260RA) | +| **PIPL — Personal Information Protection Law** | Personal Information Protection Impact Assessment (PIPIA), retention ≥ 3 years | +| **GB 45438-2025** *(mandatory)* | AI-generated content labeling — explicit + implicit (AILABEL) | +| **CAC Algorithm Filing** | Algorithm registration, dual filing process (CACFILE) | +| **GB/T 45652-2025** | Pre-training & fine-tuning data security (SBOM/MCARD) | +| **CSL 2026** | Cybersecurity incident reporting (1h / 4h+72h+30d windows) on INC | -When enabled, four China-specific document types (PIPIA, CACFILE, TC260RA, AILABEL) become available, twelve validation rules begin to enforce the new cross-references, and `devtrail compliance --region china` produces a per-framework score. Detailed guides live under `.devtrail/00-governance/` (`CHINA-REGULATORY-FRAMEWORK.md`, `TC260-IMPLEMENTATION-GUIDE.md`, `PIPL-PIPIA-GUIDE.md`, `CAC-FILING-GUIDE.md`, `GB-45438-LABELING-GUIDE.md`). +DevTrail covers six Chinese AI / data regulations as an **opt-in** regional scope. Activate by adding `regional_scope: china` to `.devtrail/config.yml`; projects without it are unaffected. When enabled, four China-specific document types (PIPIA, CACFILE, TC260RA, AILABEL) become available, twelve validation rules begin to enforce the new cross-references, and `devtrail compliance --region china` produces a per-framework score. Detailed guides live under `.devtrail/00-governance/` (`CHINA-REGULATORY-FRAMEWORK.md`, `TC260-IMPLEMENTATION-GUIDE.md`, `PIPL-PIPIA-GUIDE.md`, `CAC-FILING-GUIDE.md`, `GB-45438-LABELING-GUIDE.md`). ### 中国法规支持 @@ -206,7 +258,7 @@ DevTrail uses independent version tags for each component: | Component | Tag prefix | Example | Includes | |-----------|-----------|---------|----------| -| Framework | `fw-` | `fw-4.4.2` | Templates (12 types), governance, directives, Charter template + schema | +| Framework | `fw-` | `fw-4.5.0` | Templates (12 types), governance, directives, Charter template + schema | | CLI | `cli-` | `cli-3.6.1` | The `devtrail` binary | Check installed versions with `devtrail status` or `devtrail about`. @@ -238,7 +290,7 @@ See [CLI Reference](https://github.com/StrangeDaysTech/devtrail/blob/main/docs/a ```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-4.4.2) +# and download the latest fw-* release (e.g., fw-4.5.0) # Extract and copy to your project unzip devtrail-fw-*.zip -d your-project/ @@ -559,7 +611,7 @@ Our open-source ecosystem: | Project | Description | |---------|-------------| -| **[DevTrail](https://github.com/StrangeDaysTech/devtrail)** | AI governance platform for responsible software development | +| **[DevTrail](https://github.com/StrangeDaysTech/devtrail)** | The cognitive discipline your AI-assisted projects need | | **[arborist-metrics](https://github.com/StrangeDaysTech/arborist)** | Multi-language code complexity analysis library for Rust — [crates.io](https://crates.io/crates/arborist-metrics) | [Website](https://strangedays.tech) • [GitHub](https://github.com/StrangeDaysTech) @@ -570,7 +622,7 @@ Our open-source ecosystem:
-**DevTrail** — AI governance, documented. +**DevTrail** — Engineering discipline, externalized. Compliance, as a side effect. [⬆ Back to top](#devtrail) diff --git a/cli/Cargo.toml b/cli/Cargo.toml index 96ce14d..7c69bec 100644 --- a/cli/Cargo.toml +++ b/cli/Cargo.toml @@ -2,7 +2,7 @@ name = "devtrail-cli" version = "3.6.1" edition = "2021" -description = "CLI tool for DevTrail - Documentation Governance for AI-Assisted Development" +description = "CLI for DevTrail — the cognitive discipline your AI-assisted projects need" license = "MIT" repository = "https://github.com/StrangeDaysTech/devtrail" homepage = "https://strangedays.tech" diff --git a/dist/.devtrail/00-governance/AGENT-RULES.md b/dist/.devtrail/00-governance/AGENT-RULES.md index eb3734e..1c7bf14 100644 --- a/dist/.devtrail/00-governance/AGENT-RULES.md +++ b/dist/.devtrail/00-governance/AGENT-RULES.md @@ -270,4 +270,4 @@ When a change modifies API endpoints: --- -*DevTrail v4.4.2 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.5.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/C4-DIAGRAM-GUIDE.md b/dist/.devtrail/00-governance/C4-DIAGRAM-GUIDE.md index d3a86b6..b91457a 100644 --- a/dist/.devtrail/00-governance/C4-DIAGRAM-GUIDE.md +++ b/dist/.devtrail/00-governance/C4-DIAGRAM-GUIDE.md @@ -234,4 +234,4 @@ Use a Level 1 (Context) diagram to illustrate: --- -*DevTrail v4.4.2 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.5.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md b/dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md index 9f0a1e7..ea21eec 100644 --- a/dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md +++ b/dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md @@ -2,16 +2,19 @@ **Languages**: English | [Español](i18n/es/DOCUMENTATION-POLICY.md) | [简体中文](i18n/zh-CN/DOCUMENTATION-POLICY.md) -## Governance Framework +## Why this policy exists -This policy aligns DevTrail documentation with **ISO/IEC 42001:2023** (vertebral standard for AI Management Systems) and operationalizes: +DevTrail externalizes the cognitive discipline of senior software engineering — explicit scope, declared decisions, named risks, recorded alternatives, audited trails — into versioned files alongside the code. This policy defines the document types, metadata, and governance rules that make that discipline auditable. +As a side effect of producing those artifacts, the project accumulates evidence that maps cleanly onto the major AI governance frameworks: + +- **ISO/IEC 42001:2023** — vertebral standard for AI Management Systems - **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. +The policy is written for the engineering work first; compliance is what falls out when the work is documented with discipline. See Section 8 for the complete standards reference and the upstream repo's `Propuesta/devtrail-design-principles.md` for the product-level rationale. --- @@ -257,4 +260,4 @@ See also [ADR-2025-01-20-001] for architectural context. --- -*DevTrail v4.4.2 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.5.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/QUICK-REFERENCE.md b/dist/.devtrail/00-governance/QUICK-REFERENCE.md index c282510..0509437 100644 --- a/dist/.devtrail/00-governance/QUICK-REFERENCE.md +++ b/dist/.devtrail/00-governance/QUICK-REFERENCE.md @@ -213,4 +213,4 @@ Mark `review_required: true` when: --- -*DevTrail v4.4.2 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.5.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/QUICK-REFERENCE.md b/dist/.devtrail/QUICK-REFERENCE.md index c1ddc76..7bc334a 100644 --- a/dist/.devtrail/QUICK-REFERENCE.md +++ b/dist/.devtrail/QUICK-REFERENCE.md @@ -168,4 +168,4 @@ Mark `review_required: true` when: --- -*DevTrail v4.4.2 | [GitHub](https://github.com/StrangeDaysTech/devtrail) | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.5.0 | [GitHub](https://github.com/StrangeDaysTech/devtrail) | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/DEVTRAIL.md b/dist/DEVTRAIL.md index 2d3f84d..c3e36b5 100644 --- a/dist/DEVTRAIL.md +++ b/dist/DEVTRAIL.md @@ -6,15 +6,20 @@ --- -## Governance Context +## Why these rules exist -These rules operationalize **ISO/IEC 42001:2023** (AI Management System) — DevTrail's vertebral standard. Following them produces documented evidence compatible with: +DevTrail externalizes the cognitive discipline of senior software engineering — explicit scope, declared decisions, named risks, recorded alternatives, audited trails — into versioned files that live alongside the code. The intent is to constrain the agent's decision space so AI-assisted work stays coherent across many turns instead of drifting into hidden technical debt. +As a side effect of doing the engineering work this way, the artifacts produced map cleanly onto the major AI governance frameworks. The rules are written for the engineering work first; the compliance evidence is what falls out when the work is done with discipline. + +**Frameworks the resulting evidence aligns with:** + +- **ISO/IEC 42001:2023** (AI Management System) — vertebral standard for governance structure - **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 -**Optional**: when `.devtrail/config.yml` declares `regional_scope: china`, the framework additionally produces evidence for: +**Optional regional scope** — when `.devtrail/config.yml` declares `regional_scope: china`, the framework additionally produces evidence for: - **TC260 AI Safety Governance Framework v2.0** — risk grading (TC260RA) - **PIPL** (Personal Information Protection Law) — PIPIA, retention ≥ 3 years @@ -23,13 +28,13 @@ These rules operationalize **ISO/IEC 42001:2023** (AI Management System) — Dev - **GB/T 45652-2025** — pre-training & fine-tuning data security - **CSL 2026** — cybersecurity incident reporting (1h / 4h+72h+30d windows) -> See `AI-GOVERNANCE-POLICY.md` for the full ISO 42001 Annex A control mapping and `CHINA-REGULATORY-FRAMEWORK.md` for the China coverage matrix. +> See `AI-GOVERNANCE-POLICY.md` for the ISO 42001 Annex A control mapping and `CHINA-REGULATORY-FRAMEWORK.md` for the China coverage matrix. The product-level rationale lives in [`Propuesta/devtrail-design-principles.md`](https://github.com/StrangeDaysTech/devtrail/blob/main/Propuesta/devtrail-design-principles.md). --- ## 1. Fundamental Principle -> **"No significant change without a documented trace."** +> **"No significant change without a documented trace — and a constrained decision space for the agent."** --- diff --git a/dist/dist-manifest.yml b/dist/dist-manifest.yml index 9eb4076..4491ce4 100644 --- a/dist/dist-manifest.yml +++ b/dist/dist-manifest.yml @@ -1,4 +1,4 @@ -version: "4.4.2" +version: "4.5.0" description: "DevTrail distribution manifest" repository: "https://github.com/StrangeDaysTech/devtrail" diff --git a/docs/adopters/CLI-REFERENCE.md b/docs/adopters/CLI-REFERENCE.md index fda81dd..6a747f0 100644 --- a/docs/adopters/CLI-REFERENCE.md +++ b/docs/adopters/CLI-REFERENCE.md @@ -48,7 +48,7 @@ DevTrail uses **independent version tags** for each component: | Component | Tag prefix | Example | What it includes | |-----------|-----------|---------|------------------| -| Framework | `fw-` | `fw-4.4.2` | Templates (12 types), governance docs, directives, Charter template + schema | +| Framework | `fw-` | `fw-4.5.0` | Templates (12 types), governance docs, directives, Charter template + schema | | CLI | `cli-` | `cli-3.6.1` | The `devtrail` binary | Framework and CLI are released independently. A framework update does not require a CLI update, and vice versa. @@ -86,7 +86,7 @@ Initialize DevTrail in a project directory. ```bash $ devtrail init . -✔ Downloaded DevTrail fw-4.4.2 +✔ Downloaded DevTrail fw-4.5.0 ✔ Created .devtrail/ directory structure ✔ Created DEVTRAIL.md ✔ Configured AI agent directives @@ -108,7 +108,7 @@ If `.devtrail/` does not exist in the current directory, the framework update is ```bash $ devtrail update Updating framework... -✔ Framework updated to fw-4.4.2 +✔ Framework updated to fw-4.5.0 Updating CLI... ✔ CLI updated to cli-3.5.2 ``` @@ -125,7 +125,7 @@ Update only the framework files. Looks for the latest `fw-*` release on GitHub. ```bash $ devtrail update-framework -✔ Framework updated to fw-4.4.2 +✔ Framework updated to fw-4.5.0 ``` --- @@ -209,7 +209,7 @@ $ devtrail status Project ┌───────────┬──────────────────────────┐ │ Path │ /home/user/my-project │ - │ Framework │ fw-4.4.2 │ + │ Framework │ fw-4.5.0 │ │ CLI │ cli-3.5.2 │ │ Language │ en │ └───────────┴──────────────────────────┘ @@ -266,7 +266,7 @@ Repairing DevTrail in /home/user/my-project → Restoring 1 missing directory... ✓ Restored .devtrail/templates/ → Downloading framework to restore missing files... - Using version: fw-4.4.2 + Using version: fw-4.5.0 ✓ Restored 16 file(s) from framework → Updating checksums... @@ -797,7 +797,7 @@ Show version, authorship, and license information. $ devtrail about DevTrail CLI CLI version: cli-3.5.2 - Framework version: fw-4.4.2 + Framework version: fw-4.5.0 Author: Strange Days Tech, S.A.S. License: MIT Repository: https://github.com/StrangeDaysTech/devtrail