diff --git a/CHANGELOG.md b/CHANGELOG.md index bd47416..f19b576 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,72 @@ and this project uses [independent versioning](README.md#versioning) for Framewo --- +## Framework 4.9.0 / CLI 3.10.0 — Audit v1: zero copy/paste flow with auditor-side CLI tool use + +Closes the four axes reported in [issue #102](https://github.com/StrangeDaysTech/devtrail/issues/102) by Sentinel during its first primary-adopter run of the v0 audit-skills (CHARTER-07 of CommsHub Etapa 2). The release is **one integrated iteration** rather than four separate patches — Sentinel re-runs CHARTER-07 once after this lands, with the full v1 flow, instead of multiple times against partial fixes. + +This is the largest single audit-flow refactor since v0 shipped. Operators now invoke three skills in sequence (`audit-prompt` → `audit-execute` × N → `audit-review`) over canonical filesystem paths under `.devtrail/audits/`, and **never copy/paste prompts or reports**. The unified prompt template lifts the seven universal sections from Sentinel's pre-DevTrail audit skill (contributed via the issue), parameterized against Charter doc + originating AILOGs + git range. The review evolves from "validate + merge YAML" to a six-section consolidated analysis (Executive summary / Scope / Per-auditor evaluation / Remediation plan P0-P4 / Discarded / Auditor ratings). + +### Added (Framework) + +- **NEW skill `devtrail-audit-execute` (3 platforms)** — runs inside an auditor-side CLI (gemini-cli, claude-cli, copilot-cli, codex-cli). Reads the prompt at the canonical path, audits with tool use citing `path:line`, writes a report keyed on the auditor's model id. Auto-discovery when CHARTER-ID argument is omitted (D14). Wait-for-all-audits warning at completion is load-bearing for parallel-CLI workflows. +- **NEW unified prompt template** `dist/.devtrail/audit-prompts/audit-prompt.md` (325 lines) lifting the seven universal sections from Sentinel's `audit/SKILL.md`: REGLA ABSOLUTA — SOLO LECTURA, Tu rol (anti-cheerleader), Reglas de alcance, Paso 2 verificación obligatoria, Paso 5 calibración severidad (anti-inflation/deflation with the Etapa 12 example preserved as labeled real adopter case), Lo que NO debes hacer, Formato de salida. +- **AGENT-RULES.md §12 Audit checkpoint** updated for the 3-skill sequence + canonical paths under `.devtrail/audits/`. Wait-for-ALL-audits warning surfaces in both the message text and the rules of engagement. + +### Changed (Framework) + +- **Skills `devtrail-audit-prompt` and `devtrail-audit-review` rewritten** for v1: prompt skill no longer surfaces prompts inline (writes to canonical path; operator opens auditor CLIs). Review skill evolves to consolidated analysis generator producing `review.md` with 6 sections + 5-verdict vocabulary (VALID / PARTIALLY VALID / MISATTRIBUTED / FALSE POSITIVE / DUPLICATE) + 4-criterion weighted auditor rating (Scope precision 25% / Technical depth 25% / Bug detection 30% / False positive rate 20%). Both lifts Sentinel's `audit-review/SKILL.md` mature pre-DevTrail. +- **Adopter docs** (CLI-REFERENCE, WORKFLOWS, ADOPTION-GUIDE, QUICK-REFERENCE) in 3 langs aligned to v1 flow. + +### Removed (Framework, BREAKING within `v0.x` schemas) + +- DELETE `dist/.devtrail/audit-prompts/auditor-primary.md` (154 lines), `auditor-secondary.md` (131 lines), `calibrator-reconciler.md` (173 lines). Replaced by the single unified `audit-prompt.md`. + +### Added (CLI) + +- **NEW flag `--prepare`** on `devtrail charter audit` — generates the unified prompt at `.devtrail/audits//audit-prompt.md`. Default action when no other action flag is passed. +- **NEW flag `--merge-reports`** — reads N `report-*.md` files from the canonical audit dir, validates each against `audit-output.schema.v0.json`, emits/merges the `external_audit` YAML. Replaces the v0 two-step `--calibrate` then `--finalize`. +- **`--merge-into `** combines with `--merge-reports` (or deprecated `--finalize`); strict `requires = "finalize"` removed. +- **Schema `audit-output.schema.v0.json` evolved**: `audit_role` enum extended to `["auditor", "auditor-primary", "auditor-secondary"]` (v1 unified value + v0 legacy). NEW optional `evidence_citations: integer (>=0)` for review-skill weighting. `calibratorOutput.auditors_reconciled.maxItems` removed (v1 supports N≥2). + +### Changed (CLI) + +- **`git_range` default** changes from `HEAD~1..HEAD` to `origin/main..HEAD` (with fallback to `origin/master..HEAD`, then to `HEAD~1..HEAD` with stderr warning when no upstream is reachable). Fixes R11(A): Sentinel CHARTER-07 had 8 commits on a feature branch; v0 default sent only the last commit to auditors. +- **Canonical audit path migration**: `audit/charters//` → `.devtrail/audits//`. Per propuesta D13: namespaced under `.devtrail/` to avoid collisions with adopter-defined `audit/` folders; structure leaves room for future audit-unit categories beyond Charter. +- **Resolved prompt is one file, not two**: `audit-prompt.md` (was `auditor-{primary,secondary}.prompt.md`). +- **Reports keyed on model slug**: `report-.md` (was `auditor-{primary,secondary}.md`). + +### Fixed (CLI) + +- **R10 — resolver respects HTML comment bounds.** Issue #102: `auditor-primary.md` template's documentation header listed placeholders with literal `{{name}}` syntax, and the global `String::replace` expanded them inside the `` block, duplicating ~30k tokens of payload. Resolver now scans for comment ranges before substituting and skips placeholder replacement inside them. Unclosed comments terminate the scan early (conservative). +- **`render_external_audit_yaml` uses canonical Charter id** in `audit_notes:` instead of literal `` placeholder (pre-existing bug fixed as side-effect of refactor). + +### Deprecated (CLI) + +- **`--calibrate`** — emits warning explaining the v1 flow has no separate calibrate step (`/devtrail-audit-review` skill handles the calibrator role inline) and exits with error. Hidden in `--help`. +- **`--finalize`** — deprecated alias for `--merge-reports`. Emits warning and routes through the new path. Hidden in `--help`. + +### BREAKING (deliberate, within experimental v0.x schemas) + +- Convention of paths changes from `audit/charters/` to `.devtrail/audits/`. Audits in flight that used v0 paths (Sentinel CHARTER-07 paused state) need to be re-run under v1 — the v0 outputs stay as historical evidence at the v0 path. +- The 3 v0 prompt templates are removed. Adopters who customized them must port their changes to the unified `audit-prompt.md`. +- The CLI no longer reads from `audit/charters//` — only from `.devtrail/audits//`. + +### Tests + +- 5 new unit tests for the R10 resolver fix (HTML comment boundaries). +- 3 new integration tests for the `git_range` default change (R11(A)) — uses `init_repo_with_remote_main` helper with isolated bare-repo TempDirs to avoid parallel-test collisions. +- 9 new fixture tests for the unified prompt template (canonical path, 7 universal sections, expected placeholders, didactic Etapa 12 example, Sentinel credit, evidence discipline, schema accepts v1 + legacy, evidence_citations optional, calibrator supports N≥2). +- 17 charter_audit integration tests rewritten for v1 (10 new + 7 v0-tests-ported-to-v1 paths/flags). +- 4 new fixture tests for `devtrail-audit-execute` skill (per-platform frontmatter + cross-platform parity asserting D14 elements + wait warning + path:line discipline). +- audit_skill_test parity assertions updated for the rewritten audit-prompt and audit-review skills (six-section structure, 5-verdict vocabulary, 4-criterion rating, `external-audit-pending.yaml` for Branch B). + +### Credit + +The seven universal sections of the unified prompt template, the six-section structure of the consolidated review, the five-verdict vocabulary, and the four-criterion weighted auditor rating all lift directly from Sentinel's pre-DevTrail audit-skills (`audit/SKILL.md` and `audit-review/SKILL.md`), contributed via [issue #102](https://github.com/StrangeDaysTech/devtrail/issues/102) by José Villaseñor Montfort (StrangeDaysTech). Sentinel-specific hardcodes (paths, headings, build commands) were parameterized; didactic examples (Etapa 12 Pub/Sub stub vs gochannel active) preserved as labeled real adopter cases. + +--- + ## Framework 4.8.0 / CLI 3.9.0 — External audit skills + workflow checkpoint Phase 1 of `Propuesta/devtrail-audit-skills.md`: closes the back-half of the external multi-model audit cycle by surfacing it inside the AI assistant in the loop, and codifies a soft (never-enforced) workflow checkpoint where the agent proactively offers the audit at the right moment. External audit remains **fully optional** — the Charter's declarative scope + drift check + AILOG discipline already provide rigorous closure without it. The skills only add UX-inline; the underlying CLI orchestration is unchanged in shape, only extended with a new `--merge-into` flag to close the manual copy-paste loop. diff --git a/README.md b/README.md index 038692b..8643fff 100644 --- a/README.md +++ b/README.md @@ -259,8 +259,8 @@ DevTrail uses independent version tags for each component: | Component | Tag prefix | Example | Includes | |-----------|-----------|---------|----------| -| Framework | `fw-` | `fw-4.8.0` | Templates (12 types), governance, directives, Charter template + schema | -| CLI | `cli-` | `cli-3.9.0` | The `devtrail` binary | +| Framework | `fw-` | `fw-4.9.0` | Templates (12 types), governance, directives, Charter template + schema | +| CLI | `cli-` | `cli-3.10.0` | The `devtrail` binary | Check installed versions with `devtrail status` or `devtrail about`. @@ -292,7 +292,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.8.0) +# and download the latest fw-* release (e.g., fw-4.9.0) # Extract and copy to your project unzip devtrail-fw-*.zip -d your-project/ diff --git a/cli/Cargo.lock b/cli/Cargo.lock index f178da5..50ba783 100644 --- a/cli/Cargo.lock +++ b/cli/Cargo.lock @@ -572,7 +572,7 @@ dependencies = [ [[package]] name = "devtrail-cli" -version = "3.9.0" +version = "3.10.0" dependencies = [ "anyhow", "arborist-metrics", diff --git a/cli/Cargo.toml b/cli/Cargo.toml index d8446b8..4b2ca38 100644 --- a/cli/Cargo.toml +++ b/cli/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "devtrail-cli" -version = "3.9.0" +version = "3.10.0" edition = "2021" description = "CLI for DevTrail — the cognitive discipline your AI-assisted projects need" license = "MIT" diff --git a/dist/.devtrail/00-governance/AGENT-RULES.md b/dist/.devtrail/00-governance/AGENT-RULES.md index 6ca765f..9040daf 100644 --- a/dist/.devtrail/00-governance/AGENT-RULES.md +++ b/dist/.devtrail/00-governance/AGENT-RULES.md @@ -351,4 +351,4 @@ These are heuristics, not rigid rules — you are close to the context, refine t --- -*DevTrail v4.8.0 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.9.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 ecc9786..72df75e 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.8.0 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.9.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 e89d183..a04e183 100644 --- a/dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md +++ b/dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md @@ -307,4 +307,4 @@ See also [ADR-2025-01-20-001] for architectural context. --- -*DevTrail v4.8.0 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.9.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 c534cb2..f0a33c6 100644 --- a/dist/.devtrail/00-governance/QUICK-REFERENCE.md +++ b/dist/.devtrail/00-governance/QUICK-REFERENCE.md @@ -213,10 +213,10 @@ Mark `review_required: true` when: | `/devtrail-new` | Create any document type (interactive) | | `/devtrail-ailog` / `/devtrail-aidec` / `/devtrail-adr` | Quick shortcuts for AILOG / AIDEC / ADR | | `/devtrail-mcard` / `/devtrail-sec` | Interactive flows for Model Card / SEC assessment | -| `/devtrail-audit-prompt CHARTER-XX` *(fw-4.8.0+, refactored in fw-4.9.0)* | External multi-model audit — write unified prompt at canonical path | +| `/devtrail-audit-prompt CHARTER-XX` *(fw-4.9.0+, refactored in fw-4.9.0)* | External multi-model audit — write unified prompt at canonical path | | `/devtrail-audit-execute [CHARTER-XX]` *(fw-4.9.0+)* | Run inside an auditor CLI — read prompt, audit with tool use, write report | -| `/devtrail-audit-review CHARTER-XX` *(fw-4.8.0+, expanded in fw-4.9.0)* | Consolidate N reports into review.md (6 sections) + merge YAML into telemetry | +| `/devtrail-audit-review CHARTER-XX` *(fw-4.9.0+, expanded in fw-4.9.0)* | Consolidate N reports into review.md (6 sections) + merge YAML into telemetry | --- -*DevTrail v4.8.0 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.9.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md b/dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md index d5d1a1b..79035da 100644 --- a/dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md +++ b/dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md @@ -351,4 +351,4 @@ Son heurísticas, no reglas rígidas — estás cerca del contexto, afínalas co --- -*DevTrail v4.8.0 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.9.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md b/dist/.devtrail/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md index 1db6909..4fdb44d 100644 --- a/dist/.devtrail/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md +++ b/dist/.devtrail/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md @@ -234,4 +234,4 @@ Usar un diagrama de Nivel 1 (Contexto) para ilustrar: --- -*DevTrail v4.8.0 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.9.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/es/DOCUMENTATION-POLICY.md b/dist/.devtrail/00-governance/i18n/es/DOCUMENTATION-POLICY.md index e0a8ed8..8b52047 100644 --- a/dist/.devtrail/00-governance/i18n/es/DOCUMENTATION-POLICY.md +++ b/dist/.devtrail/00-governance/i18n/es/DOCUMENTATION-POLICY.md @@ -300,4 +300,4 @@ Ver también [ADR-2025-01-20-001] para contexto arquitectónico. --- -*DevTrail v4.8.0 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.9.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/es/QUICK-REFERENCE.md b/dist/.devtrail/00-governance/i18n/es/QUICK-REFERENCE.md index 53e8039..de64ac6 100644 --- a/dist/.devtrail/00-governance/i18n/es/QUICK-REFERENCE.md +++ b/dist/.devtrail/00-governance/i18n/es/QUICK-REFERENCE.md @@ -188,10 +188,10 @@ Marcar `review_required: true` cuando: | `/devtrail-new` | Crear cualquier tipo de documento (interactivo) | | `/devtrail-ailog` / `/devtrail-aidec` / `/devtrail-adr` | Atajos rápidos para AILOG / AIDEC / ADR | | `/devtrail-mcard` / `/devtrail-sec` | Flujos interactivos para Model Card / SEC assessment | -| `/devtrail-audit-prompt CHARTER-XX` *(fw-4.8.0+, refactorizada en fw-4.9.0)* | Auditoría externa multi-modelo — escribe prompt unificado en path canónico | +| `/devtrail-audit-prompt CHARTER-XX` *(fw-4.9.0+, refactorizada en fw-4.9.0)* | Auditoría externa multi-modelo — escribe prompt unificado en path canónico | | `/devtrail-audit-execute [CHARTER-XX]` *(fw-4.9.0+)* | Corre en una CLI auditora — lee prompt, audita con tool use, escribe report | -| `/devtrail-audit-review CHARTER-XX` *(fw-4.8.0+, expandida en fw-4.9.0)* | Consolida N reports en review.md (6 secciones) + mergea YAML en telemetría | +| `/devtrail-audit-review CHARTER-XX` *(fw-4.9.0+, expandida en fw-4.9.0)* | Consolida N reports en review.md (6 secciones) + mergea YAML en telemetría | --- -*DevTrail v4.8.0 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.9.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/zh-CN/AGENT-RULES.md b/dist/.devtrail/00-governance/i18n/zh-CN/AGENT-RULES.md index 698fbec..6a59058 100644 --- a/dist/.devtrail/00-governance/i18n/zh-CN/AGENT-RULES.md +++ b/dist/.devtrail/00-governance/i18n/zh-CN/AGENT-RULES.md @@ -346,4 +346,4 @@ confidence: high | medium | low --- -*DevTrail v4.8.0 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.9.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/zh-CN/C4-DIAGRAM-GUIDE.md b/dist/.devtrail/00-governance/i18n/zh-CN/C4-DIAGRAM-GUIDE.md index f9a3970..b454c97 100644 --- a/dist/.devtrail/00-governance/i18n/zh-CN/C4-DIAGRAM-GUIDE.md +++ b/dist/.devtrail/00-governance/i18n/zh-CN/C4-DIAGRAM-GUIDE.md @@ -234,4 +234,4 @@ Rel(api, db, "Reads/Writes", "SQL") --- -*DevTrail v4.8.0 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.9.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md b/dist/.devtrail/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md index d02f16f..685c09b 100644 --- a/dist/.devtrail/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md +++ b/dist/.devtrail/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md @@ -299,4 +299,4 @@ review_outcome: approved # approved | revisions_requested | rejec --- -*DevTrail v4.8.0 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.9.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/zh-CN/QUICK-REFERENCE.md b/dist/.devtrail/00-governance/i18n/zh-CN/QUICK-REFERENCE.md index c167d16..c7a8fa4 100644 --- a/dist/.devtrail/00-governance/i18n/zh-CN/QUICK-REFERENCE.md +++ b/dist/.devtrail/00-governance/i18n/zh-CN/QUICK-REFERENCE.md @@ -188,10 +188,10 @@ risk_level: low | medium | high | critical | `/devtrail-new` | 创建任意类型文档(交互式) | | `/devtrail-ailog` / `/devtrail-aidec` / `/devtrail-adr` | AILOG / AIDEC / ADR 的快速快捷方式 | | `/devtrail-mcard` / `/devtrail-sec` | Model Card / SEC 评估的交互流程 | -| `/devtrail-audit-prompt CHARTER-XX` *(fw-4.8.0+,在 fw-4.9.0 中重构)* | 外部多模型审计 — 在规范路径写入统一 prompt | +| `/devtrail-audit-prompt CHARTER-XX` *(fw-4.9.0+,在 fw-4.9.0 中重构)* | 外部多模型审计 — 在规范路径写入统一 prompt | | `/devtrail-audit-execute [CHARTER-XX]` *(fw-4.9.0+)* | 在审计员 CLI 中运行 — 读取 prompt,使用 tool use 审计,写入 report | -| `/devtrail-audit-review CHARTER-XX` *(fw-4.8.0+,在 fw-4.9.0 中扩展)* | 合并 N 个 reports 为 review.md(6 节)+ YAML 合并入遥测 | +| `/devtrail-audit-review CHARTER-XX` *(fw-4.9.0+,在 fw-4.9.0 中扩展)* | 合并 N 个 reports 为 review.md(6 节)+ YAML 合并入遥测 | --- -*DevTrail v4.8.0 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.9.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/QUICK-REFERENCE.md b/dist/.devtrail/QUICK-REFERENCE.md index 03753b5..7877bd7 100644 --- a/dist/.devtrail/QUICK-REFERENCE.md +++ b/dist/.devtrail/QUICK-REFERENCE.md @@ -168,4 +168,4 @@ Mark `review_required: true` when: --- -*DevTrail v4.8.0 | [GitHub](https://github.com/StrangeDaysTech/devtrail) | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.9.0 | [GitHub](https://github.com/StrangeDaysTech/devtrail) | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/dist-manifest.yml b/dist/dist-manifest.yml index fb87f25..e595126 100644 --- a/dist/dist-manifest.yml +++ b/dist/dist-manifest.yml @@ -1,4 +1,4 @@ -version: "4.8.0" +version: "4.9.0" description: "DevTrail distribution manifest" repository: "https://github.com/StrangeDaysTech/devtrail" diff --git a/docs/adopters/ADOPTION-GUIDE.md b/docs/adopters/ADOPTION-GUIDE.md index 83b2c47..fd3ce3f 100644 --- a/docs/adopters/ADOPTION-GUIDE.md +++ b/docs/adopters/ADOPTION-GUIDE.md @@ -239,7 +239,7 @@ The CLI automatically: 1. **Download the latest release** - Go to [GitHub Releases](https://github.com/StrangeDaysTech/devtrail/releases) and download the latest `fw-*` release ZIP (e.g., `fw-4.8.0`). + Go to [GitHub Releases](https://github.com/StrangeDaysTech/devtrail/releases) and download the latest `fw-*` release ZIP (e.g., `fw-4.9.0`). 2. **Extract to your project** ```bash @@ -500,7 +500,7 @@ devtrail validate ## External Audit (Optional) -From `fw-4.8.0`, when you co-implement Charters with an AI assistant in the loop (Claude Code, Gemini Code, Cursor), you can optionally run an external multi-model audit at Charter close. Two skills wrap the underlying CLI orchestration: +From `fw-4.9.0`, when you co-implement Charters with an AI assistant in the loop (Claude Code, Gemini Code, Cursor), you can optionally run an external multi-model audit at Charter close. Two skills wrap the underlying CLI orchestration: - **`/devtrail-audit-prompt CHARTER-XX`** — writes the unified audit prompt at the canonical path `.devtrail/audits//audit-prompt.md`. Operator opens N auditor-side CLIs and runs `/devtrail-audit-execute` in each. No copy/paste. - **`/devtrail-audit-execute [CHARTER-XX]`** *(fw-4.9.0+)* — runs inside an auditor-side CLI (gemini-cli, claude-cli, copilot-cli, codex-cli). Reads the prompt, audits with tool use citing `path:line`, writes a report keyed on the auditor's model id. diff --git a/docs/adopters/CLI-REFERENCE.md b/docs/adopters/CLI-REFERENCE.md index 19bae35..76a9637 100644 --- a/docs/adopters/CLI-REFERENCE.md +++ b/docs/adopters/CLI-REFERENCE.md @@ -48,8 +48,8 @@ DevTrail uses **independent version tags** for each component: | Component | Tag prefix | Example | What it includes | |-----------|-----------|---------|------------------| -| Framework | `fw-` | `fw-4.8.0` | Templates (12 types), governance docs, directives, Charter template + schema | -| CLI | `cli-` | `cli-3.9.0` | The `devtrail` binary | +| Framework | `fw-` | `fw-4.9.0` | Templates (12 types), governance docs, directives, Charter template + schema | +| CLI | `cli-` | `cli-3.10.0` | The `devtrail` binary | Framework and CLI are released independently. A framework update does not require a CLI update, and vice versa. @@ -88,7 +88,7 @@ Initialize DevTrail in a project directory. ```bash $ devtrail init . -✔ Downloaded DevTrail fw-4.8.0 +✔ Downloaded DevTrail fw-4.9.0 ✔ Created .devtrail/ directory structure ✔ Created DEVTRAIL.md ✔ Configured AI agent directives @@ -110,7 +110,7 @@ If `.devtrail/` does not exist in the current directory, the framework update is ```bash $ devtrail update Updating framework... -✔ Framework updated to fw-4.8.0 +✔ Framework updated to fw-4.9.0 Updating CLI... ✔ CLI updated to cli-3.5.2 ``` @@ -127,7 +127,7 @@ Update only the framework files. Looks for the latest `fw-*` release on GitHub. ```bash $ devtrail update-framework -✔ Framework updated to fw-4.8.0 +✔ Framework updated to fw-4.9.0 ``` --- @@ -211,7 +211,7 @@ $ devtrail status Project ┌───────────┬──────────────────────────┐ │ Path │ /home/user/my-project │ - │ Framework │ fw-4.8.0 │ + │ Framework │ fw-4.9.0 │ │ CLI │ cli-3.5.2 │ │ Language │ en │ └───────────┴──────────────────────────┘ @@ -268,7 +268,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.8.0 + Using version: fw-4.9.0 ✓ Restored 16 file(s) from framework → Updating checksums... @@ -423,7 +423,7 @@ Manage **Charters**: bounded, auditable units of work declared ex-ante and valid - `devtrail charter status` — show Charter detail, or the most recent 5 Charters - `devtrail charter close` — record post-execution telemetry and bump status to `closed` *(Phase 2, fw-4.6.0+)* - `devtrail charter drift` — detect file-vs-commit drift with AILOG-aware suppression *(Phase 2, fw-4.6.0+)* -- `devtrail charter audit` — orchestrate a multi-model external review (3-step prepare/calibrate/finalize) *(Phase 3, fw-4.8.0+)* +- `devtrail charter audit` — orchestrate a multi-model external review (3-step prepare/calibrate/finalize) *(Phase 3, fw-4.9.0+)* #### `devtrail charter new [-t XS|S|M|L] [--from-ailog | --from-spec ] [--title ] [path]` @@ -556,7 +556,7 @@ Detect file-vs-commit drift at Charter close. Wraps the framework's `.devtrail/s |---|---|---| | `CHARTER-ID` | — | Same resolution rules as `charter status` | | `--range` | `HEAD~1..HEAD` | Git revision range to check | -| `--no-ailog-suppress` *(cli-3.9.0+ always emits a confirming INFO line)* | false | Disable AILOG-aware suppression (show every declared-omitted path). When passed, the CLI always prints an `INFO: AILOG-aware suppression bypassed (would have suppressed: N path(s)…)` line — including when N=0 — so that the diagnostic mode is visible in output even on a clean run. | +| `--no-ailog-suppress` *(cli-3.10.0+ always emits a confirming INFO line)* | false | Disable AILOG-aware suppression (show every declared-omitted path). When passed, the CLI always prints an `INFO: AILOG-aware suppression bypassed (would have suppressed: N path(s)…)` line — including when N=0 — so that the diagnostic mode is visible in output even on a clean run. | | `--path` | `.` | Target project directory | **Exit codes:** `0` if no drift (or only AILOG-suppressed); `1` if there's unaccounted drift; `2` for usage errors (Charter not found, bash missing, etc.). @@ -582,14 +582,14 @@ OK all declared-omitted paths are documented in AILOGs — drift accepted. > **Platform note.** The drift check delegates to `bash`. On Linux/macOS/WSL/Git Bash this works out of the box. On Windows native without WSL, install Git Bash; a pure-Rust fallback is on the roadmap but not in fw-4.6.x. -#### Wildcard support in declared paths *(fw-4.8.0+)* +#### Wildcard support in declared paths *(fw-4.9.0+)* The drift check resolves two forms of wildcard in `## Files to modify`: | Form | Example | Use case | |---|---|---| | Ellipsis | `` `.devtrail/07-ai-audit/agent-logs/AILOG-...md` `` | Any modified path with that prefix satisfies the wildcard. Used historically when an unknown number of AILOGs would be created during execution. | -| Glob | `` `AILOG-*.md` `` or `` `src/services/foo-*.rs` `` | Any modified path matching the glob (`*` → `.*`) satisfies the wildcard. Used for bulk Charter declarations where a parameterized set is touched. Added in fw-4.8.0 after the friction surfaced in Sentinel CHARTER-04 ([issue #81](https://github.com/StrangeDaysTech/devtrail/issues/81)). | +| Glob | `` `AILOG-*.md` `` or `` `src/services/foo-*.rs` `` | Any modified path matching the glob (`*` → `.*`) satisfies the wildcard. Used for bulk Charter declarations where a parameterized set is touched. Added in fw-4.9.0 after the friction surfaced in Sentinel CHARTER-04 ([issue #81](https://github.com/StrangeDaysTech/devtrail/issues/81)). | Both forms are handled in both directions: a declared wildcard suppresses both "declared but not modified" warnings (when at least one matching file was modified) and "modified but not declared" warnings (when a modified path matches a declared wildcard). @@ -708,7 +708,7 @@ $ devtrail charter audit CHARTER-05 --merge-reports \ > **Why orchestration-only?** Implementing 3 HTTP clients (OpenAI / Google / Anthropic) is 1-2 weeks + perpetual maintenance when APIs change. v1 audit-skills extend the orchestration-only stance to a second mode (CLI auditor-side with tool use enforcement) where the operator runs their own auditor CLIs and DevTrail's prompts enforce the discipline (`cite path:line of files actually opened`). DevTrail still doesn't manage API keys, doesn't invoke APIs, doesn't maintain HTTP clients. -> **Skill alternative *(fw-4.8.0+, expanded in fw-4.9.0)*.** Three skills wrap the CLI for IDE-driven workflows: `/devtrail-audit-prompt CHARTER-ID` (calls `--prepare`), `/devtrail-audit-execute CHARTER-ID` (runs in auditor CLIs to read the prompt and write a report), and `/devtrail-audit-review CHARTER-ID` (consolidates N reports into `review.md` and merges YAML). With these skills the operator never copies/pastes prompts or reports — file exchange happens via the canonical filesystem paths under `.devtrail/audits/`. See the [Skills](#skills) section below. The CLI remains the single source of truth — the skills only add UX-inline. +> **Skill alternative *(fw-4.9.0+, expanded in fw-4.9.0)*.** Three skills wrap the CLI for IDE-driven workflows: `/devtrail-audit-prompt CHARTER-ID` (calls `--prepare`), `/devtrail-audit-execute CHARTER-ID` (runs in auditor CLIs to read the prompt and write a report), and `/devtrail-audit-review CHARTER-ID` (consolidates N reports into `review.md` and merges YAML). With these skills the operator never copies/pastes prompts or reports — file exchange happens via the canonical filesystem paths under `.devtrail/audits/`. See the [Skills](#skills) section below. The CLI remains the single source of truth — the skills only add UX-inline. --- @@ -1053,7 +1053,7 @@ Show version, authorship, and license information. $ devtrail about DevTrail CLI CLI version: cli-3.5.2 - Framework version: fw-4.8.0 + Framework version: fw-4.9.0 Author: Strange Days Tech, S.A.S. License: MIT Repository: https://github.com/StrangeDaysTech/devtrail @@ -1079,9 +1079,9 @@ DevTrail ships a set of skills (slash commands) for use inside an AI assistant ( | `/devtrail-adr` | Quick ADR creation shortcut. | `.devtrail/04-architecture/decisions/ADR-*.md` | | `/devtrail-mcard` | Interactive Model Card creation flow. | `.devtrail/09-ai-models/MCARD-*.md` | | `/devtrail-sec` | Interactive SEC (security assessment) flow. | `.devtrail/08-security/SEC-*.md` | -| `/devtrail-audit-prompt CHARTER-ID` *(fw-4.8.0+, refactored in fw-4.9.0)* | Generate the unified audit prompt for a Charter at the canonical path. Wraps `devtrail charter audit --prepare`. The operator then opens N auditor CLIs in the same repo and invokes `/devtrail-audit-execute` in each — no copy/paste. | `.devtrail/audits/<CHARTER-ID>/audit-prompt.md` | +| `/devtrail-audit-prompt CHARTER-ID` *(fw-4.9.0+, refactored in fw-4.9.0)* | Generate the unified audit prompt for a Charter at the canonical path. Wraps `devtrail charter audit --prepare`. The operator then opens N auditor CLIs in the same repo and invokes `/devtrail-audit-execute` in each — no copy/paste. | `.devtrail/audits/<CHARTER-ID>/audit-prompt.md` | | `/devtrail-audit-execute [CHARTER-ID]` *(fw-4.9.0+)* | **Run inside an auditor-side CLI** (gemini-cli, claude-cli, copilot-cli, codex-cli, ...). Reads the prepared prompt from disk, audits with tool use citing `path:line`, writes a report keyed on the auditor's model id. CHARTER-ID argument is optional — auto-discovers prompts that don't yet have a report from this model. | `.devtrail/audits/<CHARTER-ID>/report-<sluggified-model-id>.md` | -| `/devtrail-audit-review CHARTER-ID` *(fw-4.8.0+, expanded in fw-4.9.0)* | Counterpart to `/devtrail-audit-prompt`. Reads N reports under `.devtrail/audits/<CHARTER-ID>/`, verifies each finding against actual code (Explore agents in parallel), produces a six-section consolidated `review.md` (Executive summary, Scope, Per-auditor evaluation, Remediation plan P0-P4, Discarded findings, Auditor ratings), and runs `devtrail charter audit --merge-reports --merge-into` to append `external_audit:` into the Charter telemetry. If the telemetry doesn't yet exist (Charter not yet closed), writes `external-audit-pending.yaml` for later merge at close time. | `.devtrail/audits/<CHARTER-ID>/review.md`, `external_audit:` array merged into telemetry (or pending YAML) | +| `/devtrail-audit-review CHARTER-ID` *(fw-4.9.0+, expanded in fw-4.9.0)* | Counterpart to `/devtrail-audit-prompt`. Reads N reports under `.devtrail/audits/<CHARTER-ID>/`, verifies each finding against actual code (Explore agents in parallel), produces a six-section consolidated `review.md` (Executive summary, Scope, Per-auditor evaluation, Remediation plan P0-P4, Discarded findings, Auditor ratings), and runs `devtrail charter audit --merge-reports --merge-into` to append `external_audit:` into the Charter telemetry. If the telemetry doesn't yet exist (Charter not yet closed), writes `external-audit-pending.yaml` for later merge at close time. | `.devtrail/audits/<CHARTER-ID>/review.md`, `external_audit:` array merged into telemetry (or pending YAML) | ### Skill vs CLI @@ -1089,7 +1089,7 @@ The three audit skills are **wrappers** around the CLI commands and discipline. Adopters using DevTrail without an AI assistant in the loop can drive the same workflow directly via `devtrail charter audit` (`--prepare` / `--merge-reports [--merge-into <path>]`). The audit prompt at `.devtrail/audits/<id>/audit-prompt.md` works equally well pasted into a chat-based LLM if no auditor-side CLI is available — the skill just automates the file exchange. -### Audit checkpoint *(fw-4.8.0+)* +### Audit checkpoint *(fw-4.9.0+)* `.devtrail/00-governance/AGENT-RULES.md` §12 codifies a workflow checkpoint where the agent proactively offers the audit at one specific moment — when the Charter implementation is done, drift is clean, and `charter close` has not yet been invoked. The recommendation is YES/NO based on heuristics (security surface, new components, AILOG risks, complexity). External audit is **fully optional**; the checkpoint is **soft** — never blocks `charter close`, never enforced (permanent v0+v1 design decision). diff --git a/docs/i18n/es/README.md b/docs/i18n/es/README.md index 8dac396..7402b83 100644 --- a/docs/i18n/es/README.md +++ b/docs/i18n/es/README.md @@ -222,8 +222,8 @@ DevTrail usa tags de versión independientes para cada componente: | Componente | Prefijo de tag | Ejemplo | Incluye | |------------|---------------|---------|---------| -| Framework | `fw-` | `fw-4.8.0` | Plantillas (12 tipos), gobernanza, directivas, plantilla + schema de Charter | -| CLI | `cli-` | `cli-3.9.0` | El binario `devtrail` | +| Framework | `fw-` | `fw-4.9.0` | Plantillas (12 tipos), gobernanza, directivas, plantilla + schema de Charter | +| CLI | `cli-` | `cli-3.10.0` | El binario `devtrail` | Verifica las versiones instaladas con `devtrail status` o `devtrail about`. @@ -255,7 +255,7 @@ Ver [Referencia CLI](adopters/CLI-REFERENCE.md) para uso detallado. ```bash # Descargar el último release ZIP del framework desde GitHub # Ve a https://github.com/StrangeDaysTech/devtrail/releases -# y descarga el último release fw-* (ej. fw-4.8.0) +# y descarga el último release fw-* (ej. fw-4.9.0) # Extraer y copiar a tu proyecto unzip devtrail-fw-*.zip -d tu-proyecto/ diff --git a/docs/i18n/es/adopters/ADOPTION-GUIDE.md b/docs/i18n/es/adopters/ADOPTION-GUIDE.md index f915fb4..efb1dbf 100644 --- a/docs/i18n/es/adopters/ADOPTION-GUIDE.md +++ b/docs/i18n/es/adopters/ADOPTION-GUIDE.md @@ -230,7 +230,7 @@ El CLI automáticamente: 1. **Descargar el último release** - Ve a [GitHub Releases](https://github.com/StrangeDaysTech/devtrail/releases) y descarga el último release `fw-*` (ej. `fw-4.8.0`). + Ve a [GitHub Releases](https://github.com/StrangeDaysTech/devtrail/releases) y descarga el último release `fw-*` (ej. `fw-4.9.0`). 2. **Extraer en tu proyecto** ```bash @@ -494,7 +494,7 @@ devtrail validate ## Auditoría Externa (Opcional) -A partir de `fw-4.8.0`, cuando co-implementas Charters con un asistente IA en el loop (Claude Code, Gemini Code, Cursor), puedes opcionalmente correr una auditoría externa multi-modelo al cierre del Charter. Dos skills envuelven la orquestación subyacente del CLI: +A partir de `fw-4.9.0`, cuando co-implementas Charters con un asistente IA en el loop (Claude Code, Gemini Code, Cursor), puedes opcionalmente correr una auditoría externa multi-modelo al cierre del Charter. Dos skills envuelven la orquestación subyacente del CLI: - **`/devtrail-audit-prompt CHARTER-XX`** — escribe el audit prompt unificado en el path canónico `.devtrail/audits/<id>/audit-prompt.md`. El operador abre N CLIs auditoras y corre `/devtrail-audit-execute` en cada una. Sin copy/paste. - **`/devtrail-audit-execute [CHARTER-XX]`** *(fw-4.9.0+)* — corre dentro de una CLI auditora (gemini-cli, claude-cli, copilot-cli, codex-cli). Lee el prompt, audita con tool use citando `path:línea`, escribe un report con el id del modelo en el nombre. diff --git a/docs/i18n/es/adopters/CLI-REFERENCE.md b/docs/i18n/es/adopters/CLI-REFERENCE.md index 88fff8a..12ea9f5 100644 --- a/docs/i18n/es/adopters/CLI-REFERENCE.md +++ b/docs/i18n/es/adopters/CLI-REFERENCE.md @@ -48,8 +48,8 @@ DevTrail usa **tags de versión independientes** para cada componente: | Componente | Prefijo de tag | Ejemplo | Qué incluye | |------------|---------------|---------|-------------| -| Framework | `fw-` | `fw-4.8.0` | Plantillas (12 tipos), docs de gobernanza, directivas | -| CLI | `cli-` | `cli-3.9.0` | El binario `devtrail` | +| Framework | `fw-` | `fw-4.9.0` | Plantillas (12 tipos), docs de gobernanza, directivas | +| CLI | `cli-` | `cli-3.10.0` | El binario `devtrail` | Framework y CLI se publican de forma independiente. Una actualización del framework no requiere actualización del CLI, y viceversa. @@ -88,7 +88,7 @@ Inicializa DevTrail en un directorio de proyecto. ```bash $ devtrail init . -✔ Downloaded DevTrail fw-4.8.0 +✔ Downloaded DevTrail fw-4.9.0 ✔ Created .devtrail/ directory structure ✔ Created DEVTRAIL.md ✔ Configured AI agent directives @@ -109,7 +109,7 @@ Si `.devtrail/` no existe en el directorio actual, la actualización del framewo ```bash $ devtrail update Updating framework... -✔ Framework updated to fw-4.8.0 +✔ Framework updated to fw-4.9.0 Updating CLI... ✔ CLI updated to cli-3.5.2 ``` @@ -126,7 +126,7 @@ Actualiza solo los archivos del framework. Busca el último release `fw-*` en Gi ```bash $ devtrail update-framework -✔ Framework updated to fw-4.8.0 +✔ Framework updated to fw-4.9.0 ``` --- @@ -205,7 +205,7 @@ $ devtrail status DevTrail Status ─────────────── Path: /home/user/my-project -Framework version: fw-4.8.0 +Framework version: fw-4.9.0 CLI version: cli-3.5.2 Language: en Structure: ✔ Complete @@ -269,7 +269,7 @@ Valida documentos DevTrail verificando cumplimiento y corrección. | `path` | `.` (directorio actual) | Directorio del proyecto | | `--fix` | — | Corregir automáticamente problemas simples | | `--staged` | — | Validar solo archivos staged en Git (ideal para hooks pre-commit) | -| `--include-charters` | — | Validar también los Charters en `docs/charters/` contra el JSON Schema y la integridad referencial (los IDs en `originating_ailogs` resuelven; el path en `originating_spec` existe). Opt-in, default `false` para no afectar a proyectos que no usan el patrón. Por ahora solo se honra fuera de `--staged`; la validación de Charters en modo staged llega en cli-3.9.0. | +| `--include-charters` | — | Validar también los Charters en `docs/charters/` contra el JSON Schema y la integridad referencial (los IDs en `originating_ailogs` resuelven; el path en `originating_spec` existe). Opt-in, default `false` para no afectar a proyectos que no usan el patrón. Por ahora solo se honra fuera de `--staged`; la validación de Charters en modo staged llega en cli-3.10.0. | | `--check-pending-reviews` *(cli-3.7.0+)* | off | Lista documentos con `review_required: true` y sin `review_outcome` cuya antigüedad supere `--max-pending-days`. **Solo warn** — nunca falla el exit code de validate; útil para dashboards de CI sobre el backlog de aprobaciones. | | `--max-pending-days` *(cli-3.7.0+)* | `14` | Umbral en días para `--check-pending-reviews`. | @@ -490,7 +490,7 @@ Detecta drift archivo-vs-commit al cierre del Charter. Envuelve el script del fr |---|---|---| | `CHARTER-ID` | — | Mismas reglas de resolución que `charter status`. | | `--range` | `HEAD~1..HEAD` | Rango de revisiones git a chequear. | -| `--no-ailog-suppress` *(cli-3.9.0+ siempre emite una línea INFO de confirmación)* | false | Deshabilita la supresión AILOG-aware (muestra todo path declarado-omitido). Cuando se pasa el flag, el CLI siempre imprime una línea `INFO: AILOG-aware suppression bypassed (would have suppressed: N path(s)…)` — incluso cuando N=0 — para que el modo diagnóstico sea visible en la salida aun en una corrida limpia. | +| `--no-ailog-suppress` *(cli-3.10.0+ siempre emite una línea INFO de confirmación)* | false | Deshabilita la supresión AILOG-aware (muestra todo path declarado-omitido). Cuando se pasa el flag, el CLI siempre imprime una línea `INFO: AILOG-aware suppression bypassed (would have suppressed: N path(s)…)` — incluso cuando N=0 — para que el modo diagnóstico sea visible en la salida aun en una corrida limpia. | | `--path` | `.` | Directorio del proyecto. | **Códigos de salida:** `0` si no hay drift (o solo AILOG-suprimido); `1` si hay drift no contabilizado; `2` para errores de uso (Charter no encontrado, bash ausente, etc.). @@ -516,14 +516,14 @@ OK all declared-omitted paths are documented in AILOGs — drift accepted. > **Nota de plataforma.** El chequeo de drift delega en `bash`. En Linux/macOS/WSL/Git Bash funciona out-of-the-box. En Windows nativo sin WSL, instalar Git Bash; un fallback puro Rust está en el roadmap pero no en fw-4.6.x. -#### Soporte de wildcards en paths declarados *(fw-4.8.0+)* +#### Soporte de wildcards en paths declarados *(fw-4.9.0+)* El chequeo de drift resuelve dos formas de wildcard en `## Files to modify`: | Forma | Ejemplo | Caso de uso | |---|---|---| | Elipsis | `` `.devtrail/07-ai-audit/agent-logs/AILOG-...md` `` | Cualquier path modificado con ese prefijo satisface el wildcard. Usado históricamente cuando un número desconocido de AILOGs serían creados durante la ejecución. | -| Glob | `` `AILOG-*.md` `` o `` `src/services/foo-*.rs` `` | Cualquier path modificado que matchee el glob (`*` → `.*`) satisface el wildcard. Usado para declaraciones bulk de Charter donde un set parametrizado es tocado. Añadido en fw-4.8.0 tras la fricción surgida en Sentinel CHARTER-04 ([issue #81](https://github.com/StrangeDaysTech/devtrail/issues/81)). | +| Glob | `` `AILOG-*.md` `` o `` `src/services/foo-*.rs` `` | Cualquier path modificado que matchee el glob (`*` → `.*`) satisface el wildcard. Usado para declaraciones bulk de Charter donde un set parametrizado es tocado. Añadido en fw-4.9.0 tras la fricción surgida en Sentinel CHARTER-04 ([issue #81](https://github.com/StrangeDaysTech/devtrail/issues/81)). | Ambas formas se manejan en ambas direcciones: un wildcard declarado suprime tanto warnings de "declarado pero no modificado" (cuando al menos un archivo matching fue modificado) como warnings de "modificado pero no declarado" (cuando un path modificado matchea un wildcard declarado). @@ -612,7 +612,7 @@ Los adopters pueden `git add` el directorio entero `.devtrail/audits/` para un a > **¿Por qué orchestration-only?** Implementar 3 HTTP clients (OpenAI / Google / Anthropic) son 1-2 semanas + mantenimiento perpetuo. v1 audit-skills extiende el orchestration-only a un segundo modo (CLI auditor-side con tool use enforcement) donde el operador corre sus propias CLIs auditoras y los prompts de DevTrail enforzan la disciplina (`citar path:línea de archivos efectivamente abiertos`). DevTrail no maneja API keys, no invoca APIs, no mantiene HTTP clients. -> **Alternativa con skill *(fw-4.8.0+, expandida en fw-4.9.0)*.** Tres skills envuelven el CLI para flujos IDE-driven: `/devtrail-audit-prompt CHARTER-ID` (llama a `--prepare`), `/devtrail-audit-execute CHARTER-ID` (corre en CLIs auditoras para leer el prompt y escribir un report), y `/devtrail-audit-review CHARTER-ID` (consolida N reports en `review.md` y mergea YAML). Con estas skills el operador nunca copia/pega prompts ni reports — el intercambio sucede vía paths canónicos del filesystem bajo `.devtrail/audits/`. Ver la sección [Skills](#skills) más abajo. El CLI sigue siendo la fuente única de verdad — las skills solo añaden UX-inline. +> **Alternativa con skill *(fw-4.9.0+, expandida en fw-4.9.0)*.** Tres skills envuelven el CLI para flujos IDE-driven: `/devtrail-audit-prompt CHARTER-ID` (llama a `--prepare`), `/devtrail-audit-execute CHARTER-ID` (corre en CLIs auditoras para leer el prompt y escribir un report), y `/devtrail-audit-review CHARTER-ID` (consolida N reports en `review.md` y mergea YAML). Con estas skills el operador nunca copia/pega prompts ni reports — el intercambio sucede vía paths canónicos del filesystem bajo `.devtrail/audits/`. Ver la sección [Skills](#skills) más abajo. El CLI sigue siendo la fuente única de verdad — las skills solo añaden UX-inline. --- @@ -859,7 +859,7 @@ Muestra información de versión, autoría y licencia. $ devtrail about DevTrail CLI CLI version: cli-3.5.2 - Framework version: fw-4.8.0 + Framework version: fw-4.9.0 Author: Strange Days Tech, S.A.S. License: MIT Repository: https://github.com/StrangeDaysTech/devtrail @@ -885,9 +885,9 @@ DevTrail incluye un conjunto de skills (slash commands) para usar dentro de un a | `/devtrail-adr` | Atajo de creación rápida de ADR. | `.devtrail/04-architecture/decisions/ADR-*.md` | | `/devtrail-mcard` | Flujo interactivo de creación de Model Card. | `.devtrail/09-ai-models/MCARD-*.md` | | `/devtrail-sec` | Flujo interactivo SEC (security assessment). | `.devtrail/08-security/SEC-*.md` | -| `/devtrail-audit-prompt CHARTER-ID` *(fw-4.8.0+, refactorizada en fw-4.9.0)* | Genera la plantilla unificada del audit prompt para un Charter en el path canónico. Envuelve `devtrail charter audit --prepare`. El operador entonces abre N CLIs auditoras en el mismo repo e invoca `/devtrail-audit-execute` en cada una — sin copy/paste. | `.devtrail/audits/<CHARTER-ID>/audit-prompt.md` | +| `/devtrail-audit-prompt CHARTER-ID` *(fw-4.9.0+, refactorizada en fw-4.9.0)* | Genera la plantilla unificada del audit prompt para un Charter en el path canónico. Envuelve `devtrail charter audit --prepare`. El operador entonces abre N CLIs auditoras en el mismo repo e invoca `/devtrail-audit-execute` en cada una — sin copy/paste. | `.devtrail/audits/<CHARTER-ID>/audit-prompt.md` | | `/devtrail-audit-execute [CHARTER-ID]` *(fw-4.9.0+)* | **Corre dentro de una CLI auditora** (gemini-cli, claude-cli, copilot-cli, codex-cli, ...). Lee el prompt preparado del disco, audita con tool use citando `path:línea`, escribe un report con el id del modelo en el nombre. El argumento CHARTER-ID es opcional — auto-descubre prompts que aún no tienen report de este modelo. | `.devtrail/audits/<CHARTER-ID>/report-<sluggified-model-id>.md` | -| `/devtrail-audit-review CHARTER-ID` *(fw-4.8.0+, expandida en fw-4.9.0)* | Contraparte de `/devtrail-audit-prompt`. Lee N reports en `.devtrail/audits/<CHARTER-ID>/`, verifica cada finding contra el código real (Explore agents en paralelo), produce un `review.md` consolidado de seis secciones (Resumen ejecutivo, Alcance, Evaluación por auditor, Plan de remediación P0-P4, Hallazgos descartados, Calificación de auditores), y corre `devtrail charter audit --merge-reports --merge-into` para anexar `external_audit:` en la telemetría del Charter. Si la telemetría aún no existe (Charter no cerrado), escribe `external-audit-pending.yaml` para merge posterior al close. | `.devtrail/audits/<CHARTER-ID>/review.md`, array `external_audit:` mergeado en telemetría (o pending YAML) | +| `/devtrail-audit-review CHARTER-ID` *(fw-4.9.0+, expandida en fw-4.9.0)* | Contraparte de `/devtrail-audit-prompt`. Lee N reports en `.devtrail/audits/<CHARTER-ID>/`, verifica cada finding contra el código real (Explore agents en paralelo), produce un `review.md` consolidado de seis secciones (Resumen ejecutivo, Alcance, Evaluación por auditor, Plan de remediación P0-P4, Hallazgos descartados, Calificación de auditores), y corre `devtrail charter audit --merge-reports --merge-into` para anexar `external_audit:` en la telemetría del Charter. Si la telemetría aún no existe (Charter no cerrado), escribe `external-audit-pending.yaml` para merge posterior al close. | `.devtrail/audits/<CHARTER-ID>/review.md`, array `external_audit:` mergeado en telemetría (o pending YAML) | ### Skill vs CLI @@ -895,7 +895,7 @@ Las tres skills de auditoría son **wrappers** sobre los comandos del CLI y la d Adoptantes que usen DevTrail sin asistente IA en el loop pueden manejar el mismo workflow directamente vía `devtrail charter audit` (`--prepare` / `--merge-reports [--merge-into <path>]`). El audit prompt en `.devtrail/audits/<id>/audit-prompt.md` funciona igualmente bien pegado en un LLM de chat si no hay CLI auditora disponible — la skill solo automatiza el intercambio de archivos. -### Audit checkpoint *(fw-4.8.0+)* +### Audit checkpoint *(fw-4.9.0+)* `.devtrail/00-governance/AGENT-RULES.md` §12 codifica un checkpoint del workflow donde el agente proactivamente ofrece la auditoría en un momento específico — cuando la implementación del Charter está lista, drift está limpio, y `charter close` no se ha invocado aún. La recomendación es SÍ/NO basada en heurísticas (superficie de seguridad, componentes nuevos, riesgos AILOG, complejidad). La auditoría externa es **completamente opcional**; el checkpoint es **soft** — nunca bloquea `charter close`, nunca enforced (decisión de diseño v0+v1 permanente). diff --git a/docs/i18n/zh-CN/README.md b/docs/i18n/zh-CN/README.md index f3fb3eb..3fd76eb 100644 --- a/docs/i18n/zh-CN/README.md +++ b/docs/i18n/zh-CN/README.md @@ -240,8 +240,8 @@ DevTrail 为每个组件使用独立的版本标签: | 组件 | 标签前缀 | 示例 | 包含内容 | |------|----------|------|----------| -| Framework | `fw-` | `fw-4.8.0` | 模板(12 种类型)、治理文档、指令、Charter 模板 + schema | -| CLI | `cli-` | `cli-3.9.0` | `devtrail` 二进制文件 | +| Framework | `fw-` | `fw-4.9.0` | 模板(12 种类型)、治理文档、指令、Charter 模板 + schema | +| CLI | `cli-` | `cli-3.10.0` | `devtrail` 二进制文件 | 使用 `devtrail status` 或 `devtrail about` 查看已安装的版本。 @@ -273,7 +273,7 @@ DevTrail 为每个组件使用独立的版本标签: ```bash # 从 GitHub 下载最新的框架发布 ZIP # 前往 https://github.com/StrangeDaysTech/devtrail/releases -# 下载最新的 fw-* 发布(例如 fw-4.8.0) +# 下载最新的 fw-* 发布(例如 fw-4.9.0) # 解压并复制到你的项目 unzip devtrail-fw-*.zip -d your-project/ diff --git a/docs/i18n/zh-CN/adopters/ADOPTION-GUIDE.md b/docs/i18n/zh-CN/adopters/ADOPTION-GUIDE.md index 80016ab..80786eb 100644 --- a/docs/i18n/zh-CN/adopters/ADOPTION-GUIDE.md +++ b/docs/i18n/zh-CN/adopters/ADOPTION-GUIDE.md @@ -239,7 +239,7 @@ CLI 自动完成: 1. **下载最新版本** - 前往 [GitHub Releases](https://github.com/StrangeDaysTech/devtrail/releases),下载最新的 `fw-*` 版本 ZIP(例如 `fw-4.8.0`)。 + 前往 [GitHub Releases](https://github.com/StrangeDaysTech/devtrail/releases),下载最新的 `fw-*` 版本 ZIP(例如 `fw-4.9.0`)。 2. **解压到你的项目** ```bash @@ -501,7 +501,7 @@ devtrail validate ## 外部审计(可选) -自 `fw-4.8.0` 起,当你与 AI 助手在循环中协作实现 Charter 时(Claude Code、Gemini Code、Cursor),你可以在 Charter 关闭时可选地运行外部多模型审计。两个 skills 封装底层 CLI 编排: +自 `fw-4.9.0` 起,当你与 AI 助手在循环中协作实现 Charter 时(Claude Code、Gemini Code、Cursor),你可以在 Charter 关闭时可选地运行外部多模型审计。两个 skills 封装底层 CLI 编排: - **`/devtrail-audit-prompt CHARTER-XX`** — 在规范路径 `.devtrail/audits/<id>/audit-prompt.md` 处写入统一审计 prompt。操作员打开 N 个审计员 CLI 并在每个中运行 `/devtrail-audit-execute`。无需复制/粘贴。 - **`/devtrail-audit-execute [CHARTER-XX]`** *(fw-4.9.0+)* — 在审计员 CLI 中运行(gemini-cli、claude-cli、copilot-cli、codex-cli)。读取 prompt,使用 tool use 进行审计并引用 `path:line`,写入以审计员模型 ID 为键的 report。 diff --git a/docs/i18n/zh-CN/adopters/CLI-REFERENCE.md b/docs/i18n/zh-CN/adopters/CLI-REFERENCE.md index f29211a..f310e81 100644 --- a/docs/i18n/zh-CN/adopters/CLI-REFERENCE.md +++ b/docs/i18n/zh-CN/adopters/CLI-REFERENCE.md @@ -48,8 +48,8 @@ DevTrail 为每个组件使用**独立的版本标签**: | 组件 | 标签前缀 | 示例 | 包含内容 | |------|----------|------|----------| -| Framework | `fw-` | `fw-4.8.0` | 模板(12 种类型)、治理文档、指令 | -| CLI | `cli-` | `cli-3.9.0` | `devtrail` 二进制文件 | +| Framework | `fw-` | `fw-4.9.0` | 模板(12 种类型)、治理文档、指令 | +| CLI | `cli-` | `cli-3.10.0` | `devtrail` 二进制文件 | Framework 和 CLI 独立发布。Framework 更新不需要 CLI 更新,反之亦然。 @@ -88,7 +88,7 @@ devtrail status # 显示完整的安装状态,包括版本 ```bash $ devtrail init . -✔ Downloaded DevTrail fw-4.8.0 +✔ Downloaded DevTrail fw-4.9.0 ✔ Created .devtrail/ directory structure ✔ Created DEVTRAIL.md ✔ Configured AI agent directives @@ -110,7 +110,7 @@ Next: git add .devtrail/ DEVTRAIL.md && git commit -m "chore: adopt DevTrail" ```bash $ devtrail update Updating framework... -✔ Framework updated to fw-4.8.0 +✔ Framework updated to fw-4.9.0 Updating CLI... ✔ CLI updated to cli-3.5.2 ``` @@ -127,7 +127,7 @@ Updating CLI... ```bash $ devtrail update-framework -✔ Framework updated to fw-4.8.0 +✔ Framework updated to fw-4.9.0 ``` --- @@ -211,7 +211,7 @@ $ devtrail status Project ┌───────────┬──────────────────────────┐ │ Path │ /home/user/my-project │ - │ Framework │ fw-4.8.0 │ + │ Framework │ fw-4.9.0 │ │ CLI │ cli-3.5.2 │ │ Language │ en │ └───────────┴──────────────────────────┘ @@ -268,7 +268,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.8.0 + Using version: fw-4.9.0 ✓ Restored 16 file(s) from framework → Updating checksums... @@ -288,7 +288,7 @@ Repairing DevTrail in /home/user/my-project | `path` | `.`(当前目录) | 目标项目目录 | | `--fix` | — | 自动修复简单问题(例如为高风险文档添加缺失的 `review_required: true`) | | `--staged` | — | 仅验证已暂存(git add)的文件。适合 pre-commit 钩子。 | -| `--include-charters` | — | 同时根据章程 JSON Schema 和引用完整性(`originating_ailogs` 中的 ID 解析;`originating_spec` 路径存在)验证 `docs/charters/` 中的章程。Opt-in,默认 `false`,确保未使用章程模式的项目不受影响。目前仅在非 `--staged` 模式下生效;staged 模式的章程验证将在 cli-3.9.0 中加入。 | +| `--include-charters` | — | 同时根据章程 JSON Schema 和引用完整性(`originating_ailogs` 中的 ID 解析;`originating_spec` 路径存在)验证 `docs/charters/` 中的章程。Opt-in,默认 `false`,确保未使用章程模式的项目不受影响。目前仅在非 `--staged` 模式下生效;staged 模式的章程验证将在 cli-3.10.0 中加入。 | | `--check-pending-reviews` *(cli-3.7.0+)* | off | 列出所有 `review_required: true` 且没有 `review_outcome`、年龄超过 `--max-pending-days` 的文档。**仅警告** — 永不影响 validate 的退出码;适合用于 CI 仪表板上的审批积压视图。 | | `--max-pending-days` *(cli-3.7.0+)* | `14` | `--check-pending-reviews` 的天数阈值。 | @@ -507,7 +507,7 @@ $ devtrail charter close CHARTER-01 |---|---|---| | `CHARTER-ID` | — | 与 `charter status` 相同的解析规则。 | | `--range` | `HEAD~1..HEAD` | 要检查的 git 修订范围。 | -| `--no-ailog-suppress` *(cli-3.9.0+ 始终输出确认 INFO 行)* | false | 禁用 AILOG 感知抑制(显示每条已声明但被遗漏的路径)。传入此标志时,CLI 始终打印 `INFO: AILOG-aware suppression bypassed (would have suppressed: N path(s)…)` 行 — 即使 N=0 — 以便诊断模式即使在干净运行时也在输出中可见。 | +| `--no-ailog-suppress` *(cli-3.10.0+ 始终输出确认 INFO 行)* | false | 禁用 AILOG 感知抑制(显示每条已声明但被遗漏的路径)。传入此标志时,CLI 始终打印 `INFO: AILOG-aware suppression bypassed (would have suppressed: N path(s)…)` 行 — 即使 N=0 — 以便诊断模式即使在干净运行时也在输出中可见。 | | `--path` | `.` | 目标项目目录。 | **退出码:** `0` 没有漂移(或仅 AILOG 抑制);`1` 存在未计入的漂移;`2` 用法错误(章程未找到、bash 缺失等)。 @@ -533,14 +533,14 @@ OK all declared-omitted paths are documented in AILOGs — drift accepted. > **平台说明。** 漂移检查委托给 `bash`。在 Linux/macOS/WSL/Git Bash 上开箱即用。Windows 原生且无 WSL 时需安装 Git Bash;纯 Rust fallback 在路线图上但不在 fw-4.6.x 中。 -#### 已声明路径的通配符支持 *(fw-4.8.0+)* +#### 已声明路径的通配符支持 *(fw-4.9.0+)* 漂移检查在 `## Files to modify` 中解析两种通配符形式: | 形式 | 示例 | 用例 | |---|---|---| | 省略号 | `` `.devtrail/07-ai-audit/agent-logs/AILOG-...md` `` | 任何带该前缀的修改路径满足通配符。历史上用于执行期间会创建未知数量 AILOG 的情况。 | -| Glob | `` `AILOG-*.md` `` 或 `` `src/services/foo-*.rs` `` | 任何匹配该 glob(`*` → `.*`)的修改路径满足通配符。用于参数化集合被触动的批量章程声明。在 fw-4.8.0 中加入,源于 Sentinel CHARTER-04 暴露的摩擦([issue #81](https://github.com/StrangeDaysTech/devtrail/issues/81))。 | +| Glob | `` `AILOG-*.md` `` 或 `` `src/services/foo-*.rs` `` | 任何匹配该 glob(`*` → `.*`)的修改路径满足通配符。用于参数化集合被触动的批量章程声明。在 fw-4.9.0 中加入,源于 Sentinel CHARTER-04 暴露的摩擦([issue #81](https://github.com/StrangeDaysTech/devtrail/issues/81))。 | 两种形式都双向处理:声明的通配符既抑制"已声明但未修改"警告(当至少一个匹配文件被修改时),也抑制"已修改但未声明"警告(当一个修改路径匹配某个已声明通配符时)。 @@ -655,7 +655,7 @@ $ devtrail charter audit CHARTER-05 --finalize > **为什么仅编排?** 实现 3 个 HTTP 客户端(OpenAI / Google / Anthropic)需要 1-2 周 + 当 API 变化时的永久维护。Phase 3 v0 是实验性的 — CLI 的价值是 canon(prompt 形状 + output schema + 与遥测的集成),而非 API 调用本身。当 adopter 报告真实需求时,v1 可能加入 HTTP 客户端;在此之前,人在环模式与激发 Phase 3 的 Sentinel 实证 `/plan-audit` 模式相符。 -> **Skill 替代方案 *(fw-4.8.0+)*。** 当与 AI 助手在循环中协作时(Claude Code、Gemini Code、Cursor 等),skills `/devtrail-audit-prompt CHARTER-ID` 和 `/devtrail-audit-review CHARTER-ID` 封装此命令并在对话中内联展示 prompts。Skills 还处理校准器步骤(驱动对话的 Agent 运行校准器)并触发 `--finalize --merge-into`,使得 `external_audit:` 数组直接追加到遥测中无需手动复制粘贴。详见下方的 [Skills](#skills) 章节。CLI 仍是唯一真相来源 — skills 仅添加 UX-inline。 +> **Skill 替代方案 *(fw-4.9.0+)*。** 当与 AI 助手在循环中协作时(Claude Code、Gemini Code、Cursor 等),skills `/devtrail-audit-prompt CHARTER-ID` 和 `/devtrail-audit-review CHARTER-ID` 封装此命令并在对话中内联展示 prompts。Skills 还处理校准器步骤(驱动对话的 Agent 运行校准器)并触发 `--finalize --merge-into`,使得 `external_audit:` 数组直接追加到遥测中无需手动复制粘贴。详见下方的 [Skills](#skills) 章节。CLI 仍是唯一真相来源 — skills 仅添加 UX-inline。 --- @@ -993,7 +993,7 @@ $ devtrail explore --lang es # 会话内切换到西班牙语 $ devtrail about DevTrail CLI CLI version: cli-3.5.2 - Framework version: fw-4.8.0 + Framework version: fw-4.9.0 Author: Strange Days Tech, S.A.S. License: MIT Repository: https://github.com/StrangeDaysTech/devtrail @@ -1019,9 +1019,9 @@ DevTrail 提供一组 skills(slash 命令)供 AI 助手内使用(Claude Co | `/devtrail-adr` | 快速 ADR 创建快捷方式。 | `.devtrail/04-architecture/decisions/ADR-*.md` | | `/devtrail-mcard` | 交互式 Model Card 创建流程。 | `.devtrail/09-ai-models/MCARD-*.md` | | `/devtrail-sec` | 交互式 SEC(安全评估)流程。 | `.devtrail/08-security/SEC-*.md` | -| `/devtrail-audit-prompt CHARTER-ID` *(fw-4.8.0+,在 fw-4.9.0 中重构)* | 在规范路径处生成章程的统一审计 prompt。封装 `devtrail charter audit --prepare`。操作员随后在同一仓库中打开 N 个审计员 CLI,在每个中调用 `/devtrail-audit-execute` — 无需复制/粘贴。 | `.devtrail/audits/<CHARTER-ID>/audit-prompt.md` | +| `/devtrail-audit-prompt CHARTER-ID` *(fw-4.9.0+,在 fw-4.9.0 中重构)* | 在规范路径处生成章程的统一审计 prompt。封装 `devtrail charter audit --prepare`。操作员随后在同一仓库中打开 N 个审计员 CLI,在每个中调用 `/devtrail-audit-execute` — 无需复制/粘贴。 | `.devtrail/audits/<CHARTER-ID>/audit-prompt.md` | | `/devtrail-audit-execute [CHARTER-ID]` *(fw-4.9.0+)* | **在审计员 CLI 中运行**(gemini-cli、claude-cli、copilot-cli、codex-cli 等)。从磁盘读取已准备的 prompt,使用 tool use 进行审计并引用 `path:line`,写入以审计员模型 ID 为键的 report。CHARTER-ID 参数可选 — 自动发现尚未由此模型生成 report 的 prompts。 | `.devtrail/audits/<CHARTER-ID>/report-<sluggified-model-id>.md` | -| `/devtrail-audit-review CHARTER-ID` *(fw-4.8.0+,在 fw-4.9.0 中扩展)* | `/devtrail-audit-prompt` 的对应。读取 `.devtrail/audits/<CHARTER-ID>/` 下的 N 个 reports,对每个 finding 与实际代码进行交叉验证(并行 Explore agents),生成六节合并的 `review.md`(执行摘要、范围、按审计员评估、修复计划 P0-P4、丢弃的 findings、审计员评分),并运行 `devtrail charter audit --merge-reports --merge-into` 将 `external_audit:` 追加到章程遥测中。如果遥测尚不存在(章程未关闭),写入 `external-audit-pending.yaml` 供 close 时合并。 | `.devtrail/audits/<CHARTER-ID>/review.md`,`external_audit:` 数组合并入遥测(或 pending YAML) | +| `/devtrail-audit-review CHARTER-ID` *(fw-4.9.0+,在 fw-4.9.0 中扩展)* | `/devtrail-audit-prompt` 的对应。读取 `.devtrail/audits/<CHARTER-ID>/` 下的 N 个 reports,对每个 finding 与实际代码进行交叉验证(并行 Explore agents),生成六节合并的 `review.md`(执行摘要、范围、按审计员评估、修复计划 P0-P4、丢弃的 findings、审计员评分),并运行 `devtrail charter audit --merge-reports --merge-into` 将 `external_audit:` 追加到章程遥测中。如果遥测尚不存在(章程未关闭),写入 `external-audit-pending.yaml` 供 close 时合并。 | `.devtrail/audits/<CHARTER-ID>/review.md`,`external_audit:` 数组合并入遥测(或 pending YAML) | ### Skill vs CLI @@ -1029,7 +1029,7 @@ DevTrail 提供一组 skills(slash 命令)供 AI 助手内使用(Claude Co 不在循环中使用 AI 助手的 adopter 可直接通过 `devtrail charter audit`(`--prepare` / `--merge-reports [--merge-into <path>]`)驱动相同工作流。`.devtrail/audits/<id>/audit-prompt.md` 中的审计 prompt 在没有审计员 CLI 时也可粘贴到 chat 类 LLM 中使用 — skill 只是自动化文件交换。 -### 审计检查点 *(fw-4.8.0+)* +### 审计检查点 *(fw-4.9.0+)* `.devtrail/00-governance/AGENT-RULES.md` §12 编码了一个工作流检查点,其中 Agent 在某个特定时刻主动提议审计 — 当 Charter 实现完成、drift 干净,且 `charter close` 尚未调用时。推荐基于启发式给出 是/否(安全面、新组件、AILOG 风险、复杂度)。外部审计**完全可选**;检查点是**软性**的 — 永不阻塞 `charter close`,永不强制(v0+v1 永久设计决策)。