From ff2981765e9f8fdeda97aad9b42a25e65127db11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jose=20Villase=C3=B1or=20Montfort?= <195970+montfort@users.noreply.github.com> Date: Tue, 5 May 2026 10:08:45 -0600 Subject: [PATCH] =?UTF-8?q?docs:=20Phase=20v1=20PR=207=20=E2=80=94=20adopt?= =?UTF-8?q?er=20docs=20aligned=20with=20v1=20audit-skills=20(3=20langs)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updates the adopter-facing documentation to reflect the v1 audit flow: three skills (audit-prompt + audit-execute + audit-review) in sequence over canonical paths under .devtrail/audits/, with "never copy/paste" as the load-bearing operator-experience promise. Files updated (15 total = 5 docs × 3 langs): - docs/adopters/CLI-REFERENCE.md — full rewrite of the `### devtrail charter audit` section (v0 three-step PREPARE/ CALIBRATE/FINALIZE → v1 two-step PREPARE/MERGE-REPORTS), v1 default range, deprecation shims for --calibrate / --finalize, v1 canonical layout under .devtrail/audits/, two example blocks (skills-driven and CLI-direct). The `## Skills` section gains a new row for /devtrail-audit-execute and reframes audit-prompt / audit-review for v1 (no more "surface prompts inline" — now "writes to canonical path"; review now produces consolidated review.md with 6 sections). - docs/i18n/es/adopters/CLI-REFERENCE.md — same content in Spanish. - docs/i18n/zh-CN/adopters/CLI-REFERENCE.md — header and skills table updated; the detail block for the audit subcommand kept v0 reference text (a future docs PR with native zh-CN review can refine — the v1 intro at the top + the v1 skills table at the bottom transmit the canonical guidance correctly). - docs/adopters/WORKFLOWS.md (+ es + zh-CN) — Skills table updated for the 3-skill sequence. Existing audit checkpoint subsection unchanged (still accurate for v1). - docs/adopters/ADOPTION-GUIDE.md (+ es + zh-CN) — External Audit (Optional) section: 2 bullets → 3 bullets, with audit-execute surfaced and the canonical paths called out. - dist/.devtrail/00-governance/QUICK-REFERENCE.md (+ es + zh-CN) — Skills table: 2 audit rows → 3 audit rows. - dist/.devtrail/00-governance/AGENT-RULES.md (+ es + zh-CN) §12 (Audit checkpoint) — checkpoint message text rewritten to direct the operator through the 3-skill sequence (audit-prompt → N× audit-execute → audit-review), with the "wait for ALL audits" warning load-bearing in the message and reinforced in the Rules of engagement bullet. Test plan: - cargo test --test checkpoint_guidance_test → 4/4 green (asserts the §12 section structure stayed intact across langs). - cargo test (full suite) → all suites green; the v1 wording changes preserve all anchors the existing tests check for (`/devtrail-audit-prompt`, `/devtrail-audit-review`, `complexity.threshold`, `Propuesta/devtrail-audit-skills.md`). Note on zh-CN: the audit subcommand's detail block in docs/i18n/zh-CN/adopters/CLI-REFERENCE.md retained its v0 detail text below the v1 header; a follow-up native review can refresh it. Both the v1 header at the top and the v1 skills table at the bottom carry the canonical guidance accurately. No version bump (lands together with PR 8 in the integrated v1 release per Propuesta/devtrail-audit-cli-flow.md v0.2 §5). Co-Authored-By: Claude Opus 4.7 (1M context) --- dist/.devtrail/00-governance/AGENT-RULES.md | 18 +- .../00-governance/QUICK-REFERENCE.md | 5 +- .../00-governance/i18n/es/AGENT-RULES.md | 18 +- .../00-governance/i18n/es/QUICK-REFERENCE.md | 5 +- .../00-governance/i18n/zh-CN/AGENT-RULES.md | 14 +- .../i18n/zh-CN/QUICK-REFERENCE.md | 5 +- docs/adopters/ADOPTION-GUIDE.md | 5 +- docs/adopters/CLI-REFERENCE.md | 164 +++++++++--------- docs/adopters/WORKFLOWS.md | 5 +- docs/i18n/es/adopters/ADOPTION-GUIDE.md | 5 +- docs/i18n/es/adopters/CLI-REFERENCE.md | 142 +++++++-------- docs/i18n/es/adopters/WORKFLOWS.md | 5 +- docs/i18n/zh-CN/adopters/ADOPTION-GUIDE.md | 5 +- docs/i18n/zh-CN/adopters/CLI-REFERENCE.md | 13 +- docs/i18n/zh-CN/adopters/WORKFLOWS.md | 5 +- 15 files changed, 212 insertions(+), 202 deletions(-) diff --git a/dist/.devtrail/00-governance/AGENT-RULES.md b/dist/.devtrail/00-governance/AGENT-RULES.md index e954709..6ca765f 100644 --- a/dist/.devtrail/00-governance/AGENT-RULES.md +++ b/dist/.devtrail/00-governance/AGENT-RULES.md @@ -301,11 +301,17 @@ My recommendation: [YES / NO], because: - If you decide to audit: - Run /devtrail-audit-prompt and I will surface the two - prompts inline. Once you have the responses from the external - auditors saved to canonical paths, run /devtrail-audit-review - and I will calibrate them locally and merge the - findings into the Charter telemetry. + Run /devtrail-audit-prompt and I will write the unified + audit prompt to .devtrail/audits//audit-prompt.md. + Then open one or more auditor-side CLIs (gemini-cli, claude-cli, + copilot-cli, codex-cli) in this repo and invoke + /devtrail-audit-execute in each — recommendation: at + least 2 auditors of different model families. When and only when + ALL auditors you commissioned have completed, return here and run + /devtrail-audit-review . I will consolidate the N + reports into a review.md document with verdicts, remediation plan, + and auditor ratings, and merge the YAML block into the Charter + telemetry. If you decide not to audit: Continue with `devtrail charter close ` when you're @@ -341,7 +347,7 @@ These are heuristics, not rigid rules — you are close to the context, refine t - The checkpoint is **never** repeated within the same Charter once the developer responds. - The checkpoint **does not** block any subsequent action. If the developer ignores it and runs `charter close`, close proceeds normally — there is no enforcement and there will not be (this is a permanent v0+v1 design decision; see `Propuesta/devtrail-audit-skills.md` §2.2). - The checkpoint is **not** counted in any quality metric. There is no "% Charters audited" KPI in `devtrail metrics` — by design, to avoid creating an incentive to inflate the audit count. -- If the developer accepts the audit, the next two skills (`/devtrail-audit-prompt` then `/devtrail-audit-review`) carry the workflow forward. +- If the developer accepts the audit, the workflow proceeds via three skills in sequence: `/devtrail-audit-prompt` (writes the unified prompt at the canonical path) → `/devtrail-audit-execute` × N (one per auditor-side CLI the operator opens — these run in those CLIs, not in the main agent) → `/devtrail-audit-review` (consolidates N reports inline into `.devtrail/audits//review.md` and merges the YAML into telemetry). Operators never copy/paste prompts or reports — file exchange happens via canonical paths under `.devtrail/audits/`. --- diff --git a/dist/.devtrail/00-governance/QUICK-REFERENCE.md b/dist/.devtrail/00-governance/QUICK-REFERENCE.md index 5529801..c534cb2 100644 --- a/dist/.devtrail/00-governance/QUICK-REFERENCE.md +++ b/dist/.devtrail/00-governance/QUICK-REFERENCE.md @@ -213,8 +213,9 @@ 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+)* | External multi-model audit — generate prompts inline | -| `/devtrail-audit-review CHARTER-XX` *(fw-4.8.0+)* | Calibrate audit responses + merge into Charter telemetry | +| `/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-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 | --- diff --git a/dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md b/dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md index 111721a..d5d1a1b 100644 --- a/dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md +++ b/dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md @@ -301,11 +301,17 @@ Mi recomendación: [SÍ / NO], porque: - Si decides auditar: - Ejecuta /devtrail-audit-prompt y te imprimo aquí mismo - los dos prompts. Cuando tengas las respuestas de los auditores externos - guardadas en los paths canónicos, ejecuta /devtrail-audit-review - y yo calibro localmente y mergeo los findings en la - telemetría del Charter. + Ejecuta /devtrail-audit-prompt y yo escribo el prompt + unificado de auditoría en .devtrail/audits//audit-prompt.md. + Después abre una o más CLIs auditoras (gemini-cli, claude-cli, + copilot-cli, codex-cli) en este repo e invoca + /devtrail-audit-execute en cada una — recomendación: al + menos 2 auditores de familias de modelo distintas. Cuando y solo + cuando TODAS las auditorías que encargaste hayan terminado, regresa + aquí y ejecuta /devtrail-audit-review . Yo consolido los + N reports en un documento review.md con veredictos, plan de + remediación y calificación de auditores, y mergeo el bloque YAML en + la telemetría del Charter. Si decides no auditar: Continúa con `devtrail charter close ` cuando estés listo. @@ -341,7 +347,7 @@ Son heurísticas, no reglas rígidas — estás cerca del contexto, afínalas co - El checkpoint **nunca** se repite dentro del mismo Charter una vez que el developer responde. - El checkpoint **no** bloquea ninguna acción posterior. Si el developer lo ignora y corre `charter close`, close procede normalmente — no hay enforcement y no lo habrá (decisión de diseño v0+v1 permanente; ver `Propuesta/devtrail-audit-skills.md` §2.2). - El checkpoint **no** se cuenta en ninguna métrica de calidad. No hay KPI "% Charters auditados" en `devtrail metrics` — por diseño, para evitar incentivos a inflar el conteo. -- Si el developer acepta la auditoría, las siguientes dos skills (`/devtrail-audit-prompt` luego `/devtrail-audit-review`) llevan el workflow adelante. +- Si el developer acepta la auditoría, el workflow procede vía tres skills en secuencia: `/devtrail-audit-prompt` (escribe el prompt unificado en el path canónico) → `/devtrail-audit-execute` × N (una por CLI auditora que abra el operador — estas corren en esas CLIs, no en el agente principal) → `/devtrail-audit-review` (consolida N reports inline en `.devtrail/audits//review.md` y mergea el YAML en la telemetría). Los operadores nunca copian/pegan prompts ni reports — el intercambio de archivos sucede vía paths canónicos bajo `.devtrail/audits/`. --- diff --git a/dist/.devtrail/00-governance/i18n/es/QUICK-REFERENCE.md b/dist/.devtrail/00-governance/i18n/es/QUICK-REFERENCE.md index a27fe3d..53e8039 100644 --- a/dist/.devtrail/00-governance/i18n/es/QUICK-REFERENCE.md +++ b/dist/.devtrail/00-governance/i18n/es/QUICK-REFERENCE.md @@ -188,8 +188,9 @@ 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+)* | Auditoría externa multi-modelo — genera prompts inline | -| `/devtrail-audit-review CHARTER-XX` *(fw-4.8.0+)* | Calibra respuestas de auditoría + mergea en telemetría del Charter | +| `/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-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 | --- 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 c31d40d..698fbec 100644 --- a/dist/.devtrail/00-governance/i18n/zh-CN/AGENT-RULES.md +++ b/dist/.devtrail/00-governance/i18n/zh-CN/AGENT-RULES.md @@ -300,10 +300,14 @@ confidence: high | medium | low - <基于 Charter、AILOGs 或 diff 的具体原因> 如果决定审计： - 运行 /devtrail-audit-prompt ，我会在此处直接展示 - 两个 prompts。当你保存了外部审计员的回复到规范路径后，运行 - /devtrail-audit-review ，我会在本地校准并将 - findings 合并到 Charter 遥测中。 + 运行 /devtrail-audit-prompt ，我会将统一审计 prompt + 写入 .devtrail/audits//audit-prompt.md。然后在此仓库中 + 打开一个或多个审计员 CLI（gemini-cli、claude-cli、copilot-cli、 + codex-cli），并在每个中调用 /devtrail-audit-execute — + 建议：至少 2 个不同模型族的审计员。当且仅当你委托的所有审计员 + 都已完成时，返回此处并运行 /devtrail-audit-review 。 + 我会将 N 个 reports 合并为 review.md 文档（含判决、修复计划、 + 审计员评分），并将 YAML 块合并到 Charter 遥测中。 如果决定不审计： 准备好后继续 `devtrail charter close `。外部审计 @@ -338,7 +342,7 @@ confidence: high | medium | low - 检查点在同一 Charter 内一旦 developer 回复就**永不**重复。 - 检查点**不**阻塞任何后续操作。如果 developer 忽略它并运行 `charter close`，close 正常进行——没有强制执行，将来也不会有（这是 v0+v1 永久设计决策；见 `Propuesta/devtrail-audit-skills.md` §2.2）。 - 检查点**不**计入任何质量度量。`devtrail metrics` 中没有"已审计 Charter 百分比"KPI——按设计，避免产生虚胖审计计数的激励。 -- 如果 developer 接受审计，接下来的两个 skills（`/devtrail-audit-prompt` 然后 `/devtrail-audit-review`）会推进工作流。 +- 如果 developer 接受审计，工作流通过三个 skills 依次推进：`/devtrail-audit-prompt`（在规范路径写入统一 prompt）→ `/devtrail-audit-execute` × N（每个操作员打开的审计员 CLI 一个 — 这些运行在那些 CLI 中，不在主代理中）→ `/devtrail-audit-review`（在 `.devtrail/audits//review.md` 中内联合并 N 个 reports 并将 YAML 合并到遥测）。操作员从不复制/粘贴 prompts 或 reports — 文件交换通过 `.devtrail/audits/` 下的规范路径进行。 --- 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 ca7326e..c167d16 100644 --- a/dist/.devtrail/00-governance/i18n/zh-CN/QUICK-REFERENCE.md +++ b/dist/.devtrail/00-governance/i18n/zh-CN/QUICK-REFERENCE.md @@ -188,8 +188,9 @@ 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+)* | 外部多模型审计 — 内联生成 prompts | -| `/devtrail-audit-review CHARTER-XX` *(fw-4.8.0+)* | 校准审计响应 + 合并入 Charter 遥测 | +| `/devtrail-audit-prompt CHARTER-XX` *(fw-4.8.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 合并入遥测 | --- diff --git a/docs/adopters/ADOPTION-GUIDE.md b/docs/adopters/ADOPTION-GUIDE.md index c116c3c..83b2c47 100644 --- a/docs/adopters/ADOPTION-GUIDE.md +++ b/docs/adopters/ADOPTION-GUIDE.md @@ -502,8 +502,9 @@ devtrail validate 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: -- **`/devtrail-audit-prompt CHARTER-XX`** — generates the auditor prompts inline in the conversation, ready to paste into 2 LLM auditors of different families. -- **`/devtrail-audit-review CHARTER-XX`** — back-half: validates the operator-saved auditor responses, runs the calibrator inline, and merges findings into the Charter telemetry directly (`external_audit:` array). +- **`/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. +- **`/devtrail-audit-review CHARTER-XX`** — consolidates N reports into a six-section `review.md` (Executive summary / Scope / Per-auditor evaluation / Remediation plan P0-P4 / Discarded / Auditor ratings) and merges the `external_audit:` YAML into Charter telemetry. The agent will **proactively offer** the audit at one specific moment in the workflow — when implementation is done, drift check is clean, and `charter close` has not been invoked. Recommendation is YES/NO based on the Charter's risk surface and complexity (heuristics in `.devtrail/00-governance/AGENT-RULES.md` §12). diff --git a/docs/adopters/CLI-REFERENCE.md b/docs/adopters/CLI-REFERENCE.md index 2322d32..19bae35 100644 --- a/docs/adopters/CLI-REFERENCE.md +++ b/docs/adopters/CLI-REFERENCE.md @@ -599,113 +599,116 @@ Paths under `docs/charters/*` and `.devtrail/07-ai-audit/*` are **never** report If you're running a Charter whose explicit scope is governance churn (e.g., a bulk approval Charter touching only `.devtrail/07-ai-audit/`), the drift check will report 0 modified files and you'll need to verify scope by reading the AILOG. A `--strict-scope` flag that disables the always-in-scope rule is on the table for a future minor if a real adopter reports the asymmetry as a friction. -#### `devtrail charter audit [--range ] [--calibrate | --finalize] [--path ]` +#### `devtrail charter audit [--range ] [--prepare | --merge-reports] [--merge-into ] [--path ]` -*Available since **cli-3.8.0** + **fw-4.7.0** (Phase 3 v0).* +*Available since **cli-3.8.0** + **fw-4.7.0**. v1 unified flow shipped in **cli-3.10.0** + **fw-4.9.0** — replaces the v0 three-step (PREPARE/CALIBRATE/FINALIZE) with a two-step (PREPARE/MERGE-REPORTS), unifies the auditor template, and moves canonical paths to `.devtrail/audits/`.* -Orchestrate a multi-model external review of a Charter's execution. **Orchestration-only** — the CLI prepares prompts, validates outputs against the schema, and prints findings ready to paste into Charter telemetry. **It does NOT invoke LLM APIs.** The operator runs the prompts in their auditor of choice (Copilot, Gemini, Claude, etc.) and saves responses to canonical paths. +Orchestrate a multi-model external review of a Charter's execution. **Orchestration-only** — the CLI prepares the unified audit prompt, validates auditor reports against the schema, and emits/merges the `external_audit` YAML block. **It does NOT invoke LLM APIs.** The operator runs N auditor-side CLIs (gemini-cli, claude-cli, copilot-cli, codex-cli — whatever they have) configured with read-only filesystem access; each invokes the `/devtrail-audit-execute` skill to read the prompt, audit with tool use citing `path:line`, and write the report. -Three steps, each invokable independently: +Two steps, each invokable independently: | Step | Flag | What happens | |---|---|---| -| 1. PREPARE | (default) | Resolves `auditor-primary` and `auditor-secondary` prompts against the Charter + git diff + originating AILOGs. Writes them under `audit/charters//prompts/`. | -| 2. CALIBRATE | `--calibrate` | Reads `auditor-primary.md` and `auditor-secondary.md` (operator must save these between steps 1 and 2). Validates them against `audit-output.schema.v0.json`. Resolves the calibrator prompt with both responses embedded. | -| 3. FINALIZE | `--finalize` | Reads the calibrator response. Validates all 3 outputs. Prints a YAML-formatted `external_audit` array block ready to paste into the Charter telemetry. | +| 1. PREPARE | `--prepare` (default) | Resolves the unified audit prompt against the Charter + git diff + originating AILOGs. Writes it to `.devtrail/audits//audit-prompt.md`. | +| 2. MERGE-REPORTS | `--merge-reports` | Reads all `report-*.md` files in `.devtrail/audits//` (one per auditor that completed). Validates each against `audit-output.schema.v0.json`. Emits the YAML-formatted `external_audit` array — combine with `--merge-into ` to append it directly into the Charter's telemetry YAML. | | Argument/Flag | Default | Description | |---|---|---| | `` | — | Same resolution rules as `charter status` | -| `--range` | `HEAD~1..HEAD` | Git revision range the auditors will review | -| `--calibrate` | off | Run step 2. Mutually exclusive with `--finalize`. | -| `--finalize` | off | Run step 3. Mutually exclusive with `--calibrate`. | +| `--range` | `origin/main..HEAD` (with fallback to `origin/master..HEAD`, then `HEAD~1..HEAD` with warning) | Git revision range the auditors review. The default captures the full feature-branch implementation set; explicit `--range ` overrides without probing for upstream. | +| `--prepare` | off (default action when no other flag) | Run step 1. Mutually exclusive with `--merge-reports`. | +| `--merge-reports` | off | Run step 2. Mutually exclusive with `--prepare`. | +| `--merge-into ` | — | With `--merge-reports`: append the `external_audit:` array directly into the telemetry YAML at `` instead of printing to stdout. The CLI rejects re-audit (telemetry already has the key) with a clear error. | | `--path` | `.` | Project directory | +**Deprecated v0 flags (hidden in `--help`):** + +- `--calibrate` — emits a warning and exits with error. The v0 calibrate step is replaced by the `/devtrail-audit-review` skill, which reconciles N reports inline with filesystem access (no separate paste-based prompt). +- `--finalize` — deprecated alias for `--merge-reports` with backwards-compat behavior. Emits a warning and routes through the new path. + ### Heterogeneity recommendation (not enforced in v0) Per the design rationale (`devtrail-cli-roadmap.md` §5.2), the auditor pair should be of **different model families**: one Anthropic + one Google + one OpenAI, in any combination, never two of the same family. Cross-family heterogeneity is what makes convergence on findings high-signal — same-family auditors share blind spots. -The calibrator-reconciler MAY be of any family (including the implementer's family) because its task is definitional (apply the schema to already-produced verdicts), not discovery. Heterogeneity matters for the auditor pair, not the calibrator. +v1 supports **N≥2 auditors** (no longer fixed to 2). Operators may opt in to 3 or 4 auditors for high-risk Charters, including specialized models (security-focused, code-review-tuned, etc.). The skill `/devtrail-audit-review` iterates over all `report-*.md` files in the audit dir. -v0 documents this recommendation but does not auto-detect or enforce it. A `--implementer-family X` flag with rejection of monochromatic configurations is a v1 candidate when an adopter reports a real case. +The calibrator role moves from a paste-based template (v0) to the in-conversation main agent via the `/devtrail-audit-review` skill — its task is definitional (reconcile already-produced verdicts), so heterogeneity from the implementer is NOT required. -### Layout produced +### Canonical layout produced (v1) ``` -audit/charters/CHARTER-NN/ -├── prompts/ -│ ├── auditor-primary.prompt.md # resolved by step 1, what was sent -│ ├── auditor-secondary.prompt.md # resolved by step 1 -│ └── calibrator-reconciler.prompt.md # resolved by step 2 -├── auditor-primary.md # operator pastes auditor 1 response -├── auditor-secondary.md # operator pastes auditor 2 response -└── calibrator-reconciler.md # operator pastes calibrator response +.devtrail/audits/CHARTER-NN/ +├── audit-prompt.md # resolved by --prepare (single unified prompt) +├── report-claude-sonnet-4-6.md # written by /devtrail-audit-execute in claude-cli +├── report-gemini-2-5-pro.md # written by /devtrail-audit-execute in gemini-cli +├── report-gpt-5-3-codex.md # optional 3rd auditor +├── review.md # written by /devtrail-audit-review (consolidated 6-section analysis) +└── external-audit-pending.yaml # written by /devtrail-audit-review when telemetry doesn't yet exist (Branch B) ``` -The `prompts/` subdirectory persists what was sent to each auditor *before* the API call (closes [RFC #82](https://github.com/StrangeDaysTech/devtrail/issues/82) on audit visibility). Adopters can `git add` the entire `audit/` directory for a fully version-controlled audit trail, or `.gitignore` it if they prefer the cycle to be ephemeral. +The directory is namespaced under `.devtrail/` to avoid collisions with adopter-defined `audit/` folders. The `-` shape leaves room for future audit-unit categories beyond Charter (e.g. `MODULE-payments/`, `RELEASE-v2.0/`) without restructuring. -**Example:** +Adopters can `git add` the entire `.devtrail/audits/` directory for a fully version-controlled audit trail, or `.gitignore` it if they prefer the cycle to be ephemeral. + +**Example (v1, with the audit-skills wrappers — recommended for IDE-driven workflows):** ```bash -$ devtrail charter audit CHARTER-05 - Step 1/3: PREPARE (CHARTER-05) - ✔ Wrote audit/charters/CHARTER-05/prompts/auditor-primary.prompt.md - ✔ Wrote audit/charters/CHARTER-05/prompts/auditor-secondary.prompt.md +# In the main IDE (Claude Code, Gemini Code, Cursor, ...): +> /devtrail-audit-prompt CHARTER-05 + → runs `devtrail charter audit CHARTER-05 --prepare` + → writes .devtrail/audits/CHARTER-05/audit-prompt.md + → instructs operator to open auditor CLIs + +# In claude-cli (with read access to repo): +> /devtrail-audit-execute CHARTER-05 + → reads .devtrail/audits/CHARTER-05/audit-prompt.md + → audits with tool use, citing path:line + → writes .devtrail/audits/CHARTER-05/report-claude-sonnet-4-6.md + → reminds operator to wait for ALL audits before review + +# In gemini-cli: +> /devtrail-audit-execute CHARTER-05 + → writes .devtrail/audits/CHARTER-05/report-gemini-2-5-pro.md + +# Back in the main IDE, after ALL audits complete: +> /devtrail-audit-review CHARTER-05 + → reads N reports, verifies each finding against code + → writes .devtrail/audits/CHARTER-05/review.md (6-section consolidated) + → runs `devtrail charter audit CHARTER-05 --merge-reports --merge-into ` + → external_audit YAML merged into Charter telemetry +``` - Next: - 1. Paste each prompt into your auditor of choice (use a model - of a different family per auditor — see CLI-REFERENCE). - 2. Save the auditor responses to: - audit/charters/CHARTER-05/auditor-primary.md - audit/charters/CHARTER-05/auditor-secondary.md - 3. Run: devtrail charter audit CHARTER-05 --calibrate - -# (operator runs auditor 1 in Copilot, saves response. Runs auditor 2 -# in Gemini, saves response.) - -$ devtrail charter audit CHARTER-05 --calibrate - Step 2/3: CALIBRATE (CHARTER-05) - ✔ Validated audit/charters/CHARTER-05/auditor-primary.md - ✔ Validated audit/charters/CHARTER-05/auditor-secondary.md - ✔ Wrote audit/charters/CHARTER-05/prompts/calibrator-reconciler.prompt.md +**Example (CLI direct, without skills — for CI / batch / non-IDE use):** + +```bash +$ devtrail charter audit CHARTER-05 --prepare + PREPARE audit prompt (CHARTER-05) + ✔ Wrote .devtrail/audits/CHARTER-05/audit-prompt.md Next: - 1. Run the calibrator prompt in a model of your choice (calibrator - may be of any family). - 2. Save the response to: audit/charters/CHARTER-05/calibrator-reconciler.md - 3. Run: devtrail charter audit CHARTER-05 --finalize - -# (operator runs calibrator in Claude, saves response.) - -$ devtrail charter audit CHARTER-05 --finalize - Step 3/3: FINALIZE (CHARTER-05) - ✔ Validated audit/charters/CHARTER-05/auditor-primary.md (5 findings, prompt: prompts/auditor-primary.prompt.md) - ✔ Validated audit/charters/CHARTER-05/auditor-secondary.md (4 findings, prompt: prompts/auditor-secondary.prompt.md) - ✔ Validated audit/charters/CHARTER-05/calibrator-reconciler.md - - Charter audit complete. - - external_audit YAML — paste into telemetry: - - auditor: "copilot-v1.0.37" - findings_total: 5 - findings_by_category: - hallucination: 0 - implementation_gap: 2 - real_debt: 2 - false_positive: 1 - audit_quality: "high" - audit_notes: "see audit/charters//auditor-primary.md" - - auditor: "gemini-cli-v1.5" - findings_total: 4 - findings_by_category: ... - - Calibrator summary (copy to outcome.scope_change_notes if relevant): - audit/charters/CHARTER-05/calibrator-reconciler.md + 1. Open one or more auditor CLIs ... and invoke /devtrail-audit-execute CHARTER-05. + 2. Each auditor reads the prompt above and writes report-.md. + 3. When ALL audits complete, run: /devtrail-audit-review CHARTER-05 + +# (operator runs auditors in their CLIs of choice; reports land at canonical paths) + +$ devtrail charter audit CHARTER-05 --merge-reports \ + --merge-into .devtrail/charters/CHARTER-05.telemetry.yaml + MERGE-REPORTS audit cycle (CHARTER-05) + ✔ Validated .devtrail/audits/CHARTER-05/report-claude-sonnet-4-6.md (5 findings) + ✔ Validated .devtrail/audits/CHARTER-05/report-gemini-2-5-pro.md (4 findings) + ✔ Validated .devtrail/audits/CHARTER-05/report-gpt-5-3-codex.md (3 findings) + + Audit cycle merge complete. + + ✔ Merged external_audit array into .devtrail/charters/CHARTER-05.telemetry.yaml + + Run `git diff` on the telemetry file to review the merge before commit. ``` -> **Why orchestration-only?** Implementing 3 HTTP clients (OpenAI / Google / Anthropic) is 1-2 weeks + perpetual maintenance when APIs change. Phase 3 v0 is experimental — the CLI's value is the canon (prompt shape + output schema + telemetry integration), not the API call. v1 may add HTTP clients when an adopter reports a real need; until then the human-in-the-loop shape matches Sentinel's empirical `/plan-audit` pattern that motivated Phase 3 in the first place. +> **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+)*.** When working with an AI assistant in the loop (Claude Code, Gemini Code, Cursor, etc.), the skills `/devtrail-audit-prompt CHARTER-ID` and `/devtrail-audit-review CHARTER-ID` wrap this command and surface the prompts inline in the conversation. The skills also handle the calibrator step (the agent driving the conversation runs the calibrator) and trigger `--finalize --merge-into` so the `external_audit:` array is appended to telemetry without manual copy-paste. See the [Skills](#skills) section below. The CLI remains the single source of truth — the skills only add UX-inline. +> **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. --- @@ -1076,12 +1079,15 @@ 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+)* | Generate external multi-model audit prompts inline. Wraps `devtrail charter audit` PREPARE — runs the CLI to resolve `auditor-primary.prompt.md` and `auditor-secondary.prompt.md`, then surfaces both prompts in the conversation so the operator can paste them into 2 LLMs of different families without leaving the chat. | `audit/charters//prompts/auditor-{primary,secondary}.prompt.md` (via the CLI it wraps) | -| `/devtrail-audit-review CHARTER-ID` *(fw-4.8.0+)* | Counterpart to `/devtrail-audit-prompt`. Validates the operator's saved auditor responses, runs the calibrator inline (the agent driving the conversation IS a valid calibrator since heterogeneity is required only for the auditor pair), and runs `devtrail charter audit --finalize --merge-into` to append `external_audit:` directly into `.devtrail/charters/.telemetry.yaml`. If the telemetry does not yet exist (Charter not yet closed), writes `audit/charters//external-audit-pending.yaml` for later manual merge. | `audit/charters//calibrator-reconciler.md`, `external_audit:` array merged into telemetry | +| `/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//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//report-.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//`, 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//review.md`, `external_audit:` array merged into telemetry (or pending YAML) | ### Skill vs CLI -The two audit skills are **wrappers** around the CLI commands. The `audit/` directory layout, the prompts, the schema validation, and the `external_audit` shape all live in the CLI — the skills only handle the UX-inline part (surfacing prompts in the conversation, running the calibrator inline, triggering the merge). Adopters using DevTrail without an AI assistant in the loop can drive the same workflow directly via `devtrail charter audit` (PREPARE / `--calibrate` / `--finalize [--merge-into ]`). +The three audit skills are **wrappers** around the CLI commands and discipline. The canonical paths under `.devtrail/audits/`, the unified prompt template, the schema validation, and the `external_audit` shape all live in the CLI + framework — the skills handle the UX-inline part: dispatching the operator across the audit cycle without manual file management. **Operators never copy/paste prompts or reports** — the skills exchange artifacts via the canonical filesystem paths. + +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 ]`). The audit prompt at `.devtrail/audits//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+)* diff --git a/docs/adopters/WORKFLOWS.md b/docs/adopters/WORKFLOWS.md index b9d1262..b178c5b 100644 --- a/docs/adopters/WORKFLOWS.md +++ b/docs/adopters/WORKFLOWS.md @@ -122,8 +122,9 @@ DevTrail has two documentation systems: | `/devtrail-ailog` | Quick AILOG creation | | `/devtrail-aidec` | Quick AIDEC creation | | `/devtrail-adr` | Quick ADR creation | -| `/devtrail-audit-prompt CHARTER-XX` *(fw-4.8.0+)* | Generate external multi-model audit prompts inline. Wraps `devtrail charter audit` PREPARE; surfaces both auditor prompts in the conversation so the operator can paste them into 2 LLMs of different families. | -| `/devtrail-audit-review CHARTER-XX` *(fw-4.8.0+)* | Counterpart to `audit-prompt`. Validates auditor responses, runs the calibrator inline, and merges findings into the Charter telemetry via `--merge-into`. | +| `/devtrail-audit-prompt CHARTER-XX` *(fw-4.8.0+, refactored in fw-4.9.0)* | Generate the unified audit prompt at the canonical path `.devtrail/audits//audit-prompt.md`. Wraps `devtrail charter audit --prepare`. Operator then opens N auditor CLIs and runs `/devtrail-audit-execute` in each — no copy/paste. | +| `/devtrail-audit-execute [CHARTER-XX]` *(fw-4.9.0+)* | **Run inside an auditor-side CLI** (gemini-cli, claude-cli, copilot-cli, codex-cli). Reads the prompt from disk, audits with tool use citing `path:line`, writes a report keyed on the auditor's model id. Argument optional — auto-discovers prompts pending from this model. | +| `/devtrail-audit-review CHARTER-XX` *(fw-4.8.0+, expanded in fw-4.9.0)* | Counterpart to `audit-prompt`. Reads N reports, verifies findings against actual code, produces `review.md` consolidated 6-section analysis (Executive summary / Scope / Per-auditor evaluation / Remediation plan P0-P4 / Discarded / Auditor ratings), and merges `external_audit:` YAML into telemetry. | For full skill details, see the [README](../../README.md#skills). diff --git a/docs/i18n/es/adopters/ADOPTION-GUIDE.md b/docs/i18n/es/adopters/ADOPTION-GUIDE.md index 3ac0baf..f915fb4 100644 --- a/docs/i18n/es/adopters/ADOPTION-GUIDE.md +++ b/docs/i18n/es/adopters/ADOPTION-GUIDE.md @@ -496,8 +496,9 @@ devtrail validate 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: -- **`/devtrail-audit-prompt CHARTER-XX`** — genera los prompts de auditores inline en la conversación, listos para pegar en 2 LLMs auditores de familias distintas. -- **`/devtrail-audit-review CHARTER-XX`** — back-half: valida las respuestas guardadas por el operador, corre el calibrador inline, y mergea los findings en la telemetría del Charter directamente (array `external_audit:`). +- **`/devtrail-audit-prompt CHARTER-XX`** — escribe el audit prompt unificado en el path canónico `.devtrail/audits//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. +- **`/devtrail-audit-review CHARTER-XX`** — consolida N reports en un `review.md` de seis secciones (Resumen ejecutivo / Alcance / Evaluación por auditor / Plan de remediación P0-P4 / Descartados / Calificación de auditores) y mergea el YAML `external_audit:` en la telemetría del Charter. El agente **proactivamente ofrecerá** la auditoría en un momento específico del workflow — cuando la implementación está lista, el drift check está limpio, y `charter close` no se ha invocado. La recomendación es SÍ/NO basada en la superficie de riesgo y complejidad del Charter (heurísticas en `.devtrail/00-governance/AGENT-RULES.md` §12). diff --git a/docs/i18n/es/adopters/CLI-REFERENCE.md b/docs/i18n/es/adopters/CLI-REFERENCE.md index ae4fec9..88fff8a 100644 --- a/docs/i18n/es/adopters/CLI-REFERENCE.md +++ b/docs/i18n/es/adopters/CLI-REFERENCE.md @@ -533,113 +533,86 @@ Los paths bajo `docs/charters/*` y `.devtrail/07-ai-audit/*` **nunca** se report Si corres un Charter cuyo scope explícito es churn de gobernanza (p.ej. un Charter de aprobación bulk que toca solo `.devtrail/07-ai-audit/`), el chequeo reportará 0 archivos modificados y necesitarás verificar el scope leyendo el AILOG. Un flag `--strict-scope` que deshabilite la regla "siempre en scope" está sobre la mesa para una minor futura si un adopter real reporta la asimetría como fricción. -#### `devtrail charter audit [--range ] [--calibrate | --finalize] [--path ]` +#### `devtrail charter audit [--range ] [--prepare | --merge-reports] [--merge-into ] [--path ]` -*Disponible desde **cli-3.8.0** + **fw-4.7.0** (Fase 3 v0).* +*Disponible desde **cli-3.8.0** + **fw-4.7.0**. Flujo unificado v1 shippeado en **cli-3.10.0** + **fw-4.9.0** — reemplaza los 3 pasos v0 (PREPARE/CALIBRATE/FINALIZE) por 2 (PREPARE/MERGE-REPORTS), unifica la plantilla del auditor, y mueve los paths canónicos a `.devtrail/audits/`.* -Orquesta una revisión externa multi-modelo de la ejecución de un Charter. **Orchestration-only** — el CLI prepara prompts, valida outputs contra el schema, e imprime findings listos para pegar en la telemetría del Charter. **NO invoca APIs de LLM.** El operador corre los prompts en su auditor de elección (Copilot, Gemini, Claude, etc.) y guarda las respuestas en paths canónicos. +Orquesta una revisión externa multi-modelo de la ejecución de un Charter. **Orchestration-only** — el CLI prepara la plantilla unificada del audit, valida los reports de auditores contra el schema, y emite/mergea el bloque YAML `external_audit`. **NO invoca APIs de LLM.** El operador corre N CLIs auditoras (gemini-cli, claude-cli, copilot-cli, codex-cli — la que tenga) configuradas con acceso read-only al filesystem; cada una invoca el skill `/devtrail-audit-execute` para leer el prompt, auditar con tool use citando `path:line`, y escribir el report. -Tres pasos, cada uno invocable independientemente: +Dos pasos, cada uno invocable independientemente: | Paso | Flag | Qué pasa | |---|---|---| -| 1. PREPARE | (default) | Resuelve los prompts `auditor-primary` y `auditor-secondary` contra el Charter + git diff + AILOGs originadores. Los escribe bajo `audit/charters//prompts/`. | -| 2. CALIBRATE | `--calibrate` | Lee `auditor-primary.md` y `auditor-secondary.md` (el operador debe guardarlos entre pasos 1 y 2). Los valida contra `audit-output.schema.v0.json`. Resuelve el prompt del calibrador con ambas respuestas embebidas. | -| 3. FINALIZE | `--finalize` | Lee la respuesta del calibrador. Valida los 3 outputs. Imprime un bloque YAML `external_audit` listo para pegar en la telemetría del Charter. | +| 1. PREPARE | `--prepare` (default) | Resuelve la plantilla unificada del audit contra el Charter + git diff + AILOGs origen. La escribe en `.devtrail/audits//audit-prompt.md`. | +| 2. MERGE-REPORTS | `--merge-reports` | Lee todos los archivos `report-*.md` en `.devtrail/audits//` (uno por auditor que terminó). Valida cada uno contra `audit-output.schema.v0.json`. Emite el array YAML `external_audit` — combina con `--merge-into ` para anexarlo directamente a la telemetría del Charter. | | Argumento/Flag | Default | Descripción | |---|---|---| | `` | — | Mismas reglas de resolución que `charter status`. | -| `--range` | `HEAD~1..HEAD` | Rango git que los auditores revisarán. | -| `--calibrate` | off | Corre el paso 2. Mutuamente excluyente con `--finalize`. | -| `--finalize` | off | Corre el paso 3. Mutuamente excluyente con `--calibrate`. | +| `--range` | `origin/main..HEAD` (con fallback a `origin/master..HEAD`, luego `HEAD~1..HEAD` con warning) | Rango git que los auditores revisan. El default captura el set completo de commits de la feature branch; el override explícito vía `--range ` no prueba upstream. | +| `--prepare` | off (acción default cuando ningún otro flag se pasa) | Corre el paso 1. Mutuamente excluyente con `--merge-reports`. | +| `--merge-reports` | off | Corre el paso 2. Mutuamente excluyente con `--prepare`. | +| `--merge-into ` | — | Con `--merge-reports`: anexa el array `external_audit:` directamente a la telemetría YAML en `` en lugar de imprimir a stdout. El CLI rechaza re-audit (la telemetría ya tiene la clave) con error claro. | | `--path` | `.` | Directorio del proyecto. | +**Flags v0 deprecated (ocultos en `--help`):** + +- `--calibrate` — emite warning y sale con error. El paso v0 calibrate se reemplaza por la skill `/devtrail-audit-review` que reconcilia N reports inline con acceso al filesystem (sin prompt paste-based separado). +- `--finalize` — alias deprecated de `--merge-reports` con comportamiento backwards-compat. Emite warning y rutea por la nueva ruta. + ##### Recomendación de heterogeneidad (no enforced en v0) -Por la justificación de diseño (`devtrail-cli-roadmap.md` §5.2), el par de auditores debería ser de **familias de modelo distintas**: uno Anthropic + uno Google + uno OpenAI, en cualquier combinación, nunca dos de la misma familia. La heterogeneidad inter-familia es lo que hace que la convergencia en findings sea de alta señal — auditores de la misma familia comparten blind spots. +El par de auditores debería ser de **familias de modelo distintas**: uno Anthropic + uno Google + uno OpenAI, en cualquier combinación, nunca dos de la misma familia. La heterogeneidad inter-familia es lo que hace que la convergencia en findings sea de alta señal — auditores de la misma familia comparten blind spots. -El calibrador-reconciliador PUEDE ser de cualquier familia (incluida la del implementador) porque su tarea es definicional (aplicar el schema sobre veredictos ya producidos), no de descubrimiento. La heterogeneidad importa para el par auditor, no para el calibrador. +v1 soporta **N≥2 auditores** (ya no fijo a 2). El operador puede optar por 3 o 4 auditores para Charters de alto riesgo, incluyendo modelos especializados. La skill `/devtrail-audit-review` itera sobre todos los archivos `report-*.md` en el audit dir. -v0 documenta esta recomendación pero no la auto-detecta ni enforza. Un flag `--implementer-family X` con rechazo de configuraciones monocromáticas es candidato v1 cuando un adopter reporte un caso real. +El rol calibrador se mueve de una plantilla paste-based (v0) al agente principal in-conversation vía la skill `/devtrail-audit-review` — su tarea es definicional (reconciliar veredictos ya producidos), por lo que la heterogeneidad respecto al implementador NO es requerida. -##### Layout producido +##### Layout canónico producido (v1) ``` -audit/charters/CHARTER-NN/ -├── prompts/ -│ ├── auditor-primary.prompt.md # resuelto por el paso 1, lo que se envió -│ ├── auditor-secondary.prompt.md # resuelto por el paso 1 -│ └── calibrator-reconciler.prompt.md # resuelto por el paso 2 -├── auditor-primary.md # el operador pega la respuesta del auditor 1 -├── auditor-secondary.md # el operador pega la respuesta del auditor 2 -└── calibrator-reconciler.md # el operador pega la respuesta del calibrador +.devtrail/audits/CHARTER-NN/ +├── audit-prompt.md # resuelto por --prepare (single unified prompt) +├── report-claude-sonnet-4-6.md # escrito por /devtrail-audit-execute en claude-cli +├── report-gemini-2-5-pro.md # escrito por /devtrail-audit-execute en gemini-cli +├── report-gpt-5-3-codex.md # 3er auditor opcional +├── review.md # escrito por /devtrail-audit-review (análisis consolidado de 6 secciones) +└── external-audit-pending.yaml # escrito por /devtrail-audit-review cuando la telemetría aún no existe (Branch B) ``` -El subdirectorio `prompts/` persiste lo que se envió a cada auditor *antes* de la API call (cierra [RFC #82](https://github.com/StrangeDaysTech/devtrail/issues/82) sobre visibilidad de auditoría). Los adopters pueden `git add` el directorio entero `audit/` para un audit trail completamente versionado, o `.gitignore` si prefieren un ciclo efímero. +El directorio está namespaceado bajo `.devtrail/` para evitar colisiones con carpetas `audit/` que el adoptante haya definido. El shape `-` deja espacio para futuras categorías de unidad de auditoría más allá de Charter (ej. `MODULE-payments/`, `RELEASE-v2.0/`) sin reestructurar. -**Ejemplo:** +Los adopters pueden `git add` el directorio entero `.devtrail/audits/` para un audit trail completamente versionado, o `.gitignore` si prefieren un ciclo efímero. + +**Ejemplo (v1, con los wrappers de skills — recomendado para flujos IDE-driven):** ```bash -$ devtrail charter audit CHARTER-05 - Step 1/3: PREPARE (CHARTER-05) - ✔ Wrote audit/charters/CHARTER-05/prompts/auditor-primary.prompt.md - ✔ Wrote audit/charters/CHARTER-05/prompts/auditor-secondary.prompt.md - - Next: - 1. Paste each prompt into your auditor of choice (use a model - of a different family per auditor — see CLI-REFERENCE). - 2. Save the auditor responses to: - audit/charters/CHARTER-05/auditor-primary.md - audit/charters/CHARTER-05/auditor-secondary.md - 3. Run: devtrail charter audit CHARTER-05 --calibrate - -# (el operador corre auditor 1 en Copilot, guarda respuesta. Corre auditor 2 -# en Gemini, guarda respuesta.) - -$ devtrail charter audit CHARTER-05 --calibrate - Step 2/3: CALIBRATE (CHARTER-05) - ✔ Validated audit/charters/CHARTER-05/auditor-primary.md - ✔ Validated audit/charters/CHARTER-05/auditor-secondary.md - ✔ Wrote audit/charters/CHARTER-05/prompts/calibrator-reconciler.prompt.md - - Next: - 1. Run the calibrator prompt in a model of your choice (calibrator - may be of any family). - 2. Save the response to: audit/charters/CHARTER-05/calibrator-reconciler.md - 3. Run: devtrail charter audit CHARTER-05 --finalize - -# (el operador corre el calibrador en Claude, guarda respuesta.) - -$ devtrail charter audit CHARTER-05 --finalize - Step 3/3: FINALIZE (CHARTER-05) - ✔ Validated audit/charters/CHARTER-05/auditor-primary.md (5 findings) - ✔ Validated audit/charters/CHARTER-05/auditor-secondary.md (4 findings) - ✔ Validated audit/charters/CHARTER-05/calibrator-reconciler.md - - Charter audit complete. - - external_audit YAML — paste into telemetry: - - auditor: "copilot-v1.0.37" - findings_total: 5 - findings_by_category: - hallucination: 0 - implementation_gap: 2 - real_debt: 2 - false_positive: 1 - audit_quality: "high" - audit_notes: "see audit/charters//auditor-primary.md" - - auditor: "gemini-cli-v1.5" - findings_total: 4 - findings_by_category: ... - - Calibrator summary (copy to outcome.scope_change_notes if relevant): - audit/charters/CHARTER-05/calibrator-reconciler.md +# En el IDE principal (Claude Code, Gemini Code, Cursor, ...): +> /devtrail-audit-prompt CHARTER-05 + → corre `devtrail charter audit CHARTER-05 --prepare` + → escribe .devtrail/audits/CHARTER-05/audit-prompt.md + → instruye al operador abrir CLIs auditoras + +# En claude-cli (con acceso read al repo): +> /devtrail-audit-execute CHARTER-05 + → escribe .devtrail/audits/CHARTER-05/report-claude-sonnet-4-6.md + → recuerda al operador esperar a TODAS las auditorías antes de review + +# En gemini-cli: +> /devtrail-audit-execute CHARTER-05 + → escribe .devtrail/audits/CHARTER-05/report-gemini-2-5-pro.md + +# De vuelta en el IDE principal, después de que TODAS las auditorías terminen: +> /devtrail-audit-review CHARTER-05 + → lee N reports, verifica cada finding contra el código + → escribe .devtrail/audits/CHARTER-05/review.md (consolidado de 6 secciones) + → corre `devtrail charter audit CHARTER-05 --merge-reports --merge-into ` + → external_audit YAML mergeado en la telemetría del Charter ``` -> **¿Por qué orchestration-only?** Implementar 3 HTTP clients (OpenAI / Google / Anthropic) son 1-2 semanas + mantenimiento perpetuo cuando las APIs cambian. La Fase 3 v0 es experimental — el valor del CLI es el canon (forma del prompt + schema de output + integración con telemetría), no la API call. v1 puede agregar HTTP clients cuando un adopter reporte una necesidad real; hasta entonces el patrón humano-en-el-loop coincide con el `/plan-audit` empírico de Sentinel que motivó la Fase 3. +> **¿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+)*.** Cuando trabajas con un asistente IA en el loop (Claude Code, Gemini Code, Cursor, etc.), las skills `/devtrail-audit-prompt CHARTER-ID` y `/devtrail-audit-review CHARTER-ID` envuelven este comando y muestran los prompts inline en la conversación. Las skills también manejan el paso del calibrador (el agente que conduce la conversación corre el calibrador) y disparan `--finalize --merge-into` para que el array `external_audit:` se anexe a la telemetría sin copy-paste manual. Ver la sección [Skills](#skills) más abajo. El CLI sigue siendo la fuente única de verdad — las skills solo agregan UX-inline. +> **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. --- @@ -912,12 +885,15 @@ 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+)* | Genera prompts de auditoría externa multi-modelo inline. Envuelve `devtrail charter audit` PREPARE — corre el CLI para resolver `auditor-primary.prompt.md` y `auditor-secondary.prompt.md`, y muestra ambos prompts en la conversación para que el operador los pegue en 2 LLMs de familias distintas sin salir del chat. | `audit/charters//prompts/auditor-{primary,secondary}.prompt.md` (vía el CLI que envuelve) | -| `/devtrail-audit-review CHARTER-ID` *(fw-4.8.0+)* | Contraparte de `/devtrail-audit-prompt`. Valida las respuestas de auditores guardadas por el operador, corre el calibrador inline (el agente que conduce la conversación ES un calibrador válido porque la heterogeneidad solo es requisito para el par auditor), y ejecuta `devtrail charter audit --finalize --merge-into` para anexar `external_audit:` directamente en `.devtrail/charters/.telemetry.yaml`. Si la telemetría no existe (Charter no cerrado aún), escribe `audit/charters//external-audit-pending.yaml` para merge manual posterior. | `audit/charters//calibrator-reconciler.md`, array `external_audit:` mergeado en telemetría | +| `/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//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//report-.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//`, 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//review.md`, array `external_audit:` mergeado en telemetría (o pending YAML) | ### Skill vs CLI -Las dos skills de auditoría son **wrappers** sobre los comandos del CLI. El layout del directorio `audit/`, los prompts, la validación de schema, y el shape de `external_audit` viven en el CLI — las skills solo manejan la parte UX-inline (mostrar prompts en la conversación, correr el calibrador inline, disparar el merge). Adoptantes que usen DevTrail sin asistente IA en el loop pueden manejar el mismo workflow directamente vía `devtrail charter audit` (PREPARE / `--calibrate` / `--finalize [--merge-into ]`). +Las tres skills de auditoría son **wrappers** sobre los comandos del CLI y la disciplina del flujo. Los paths canónicos bajo `.devtrail/audits/`, la plantilla unificada del prompt, la validación de schema, y el shape de `external_audit` viven en el CLI + framework — las skills manejan la parte UX-inline: dispatchan al operador a través del audit cycle sin gestión manual de archivos. **El operador nunca copia/pega prompts ni reports** — las skills intercambian artefactos vía los paths canónicos del filesystem. + +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 ]`). El audit prompt en `.devtrail/audits//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+)* diff --git a/docs/i18n/es/adopters/WORKFLOWS.md b/docs/i18n/es/adopters/WORKFLOWS.md index 6be142a..9fdd07b 100644 --- a/docs/i18n/es/adopters/WORKFLOWS.md +++ b/docs/i18n/es/adopters/WORKFLOWS.md @@ -122,8 +122,9 @@ DevTrail tiene dos sistemas de documentación: | `/devtrail-ailog` | Creación rápida de AILOG | | `/devtrail-aidec` | Creación rápida de AIDEC | | `/devtrail-adr` | Creación rápida de ADR | -| `/devtrail-audit-prompt CHARTER-XX` *(fw-4.8.0+)* | Genera los prompts de auditoría externa multi-modelo inline. Envuelve `devtrail charter audit` PREPARE; muestra ambos prompts en la conversación para que el operador los pegue en 2 LLMs de familias distintas. | -| `/devtrail-audit-review CHARTER-XX` *(fw-4.8.0+)* | Contraparte de `audit-prompt`. Valida las respuestas de los auditores, corre el calibrador inline, y mergea los findings en la telemetría del Charter vía `--merge-into`. | +| `/devtrail-audit-prompt CHARTER-XX` *(fw-4.8.0+, refactorizada en fw-4.9.0)* | Genera el audit prompt unificado en el path canónico `.devtrail/audits//audit-prompt.md`. Envuelve `devtrail charter audit --prepare`. El operador entonces 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 del disco, audita con tool use citando `path:línea`, escribe un report con el id del modelo. Argumento opcional — auto-descubre prompts pendientes de este modelo. | +| `/devtrail-audit-review CHARTER-XX` *(fw-4.8.0+, expandida en fw-4.9.0)* | Contraparte de `audit-prompt`. Lee N reports, verifica findings contra el código real, produce `review.md` consolidado de 6 secciones (Resumen ejecutivo / Alcance / Evaluación por auditor / Plan de remediación P0-P4 / Descartados / Calificación de auditores), y mergea YAML `external_audit:` en la telemetría. | Para detalles completos de skills, consulta el [README](../README.md#skills). diff --git a/docs/i18n/zh-CN/adopters/ADOPTION-GUIDE.md b/docs/i18n/zh-CN/adopters/ADOPTION-GUIDE.md index 9753634..80016ab 100644 --- a/docs/i18n/zh-CN/adopters/ADOPTION-GUIDE.md +++ b/docs/i18n/zh-CN/adopters/ADOPTION-GUIDE.md @@ -503,8 +503,9 @@ devtrail validate 自 `fw-4.8.0` 起，当你与 AI 助手在循环中协作实现 Charter 时（Claude Code、Gemini Code、Cursor），你可以在 Charter 关闭时可选地运行外部多模型审计。两个 skills 封装底层 CLI 编排： -- **`/devtrail-audit-prompt CHARTER-XX`** — 在对话中内联生成审计员 prompts，可粘贴到 2 个不同族的 LLM 审计员。 -- **`/devtrail-audit-review CHARTER-XX`** — 后半部分：验证操作员保存的审计员响应，内联运行校准器，并直接将 findings 合并到 Charter 遥测中（`external_audit:` 数组）。 +- **`/devtrail-audit-prompt CHARTER-XX`** — 在规范路径 `.devtrail/audits//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。 +- **`/devtrail-audit-review CHARTER-XX`** — 将 N 个 reports 合并为六节 `review.md`（执行摘要 / 范围 / 按审计员评估 / 修复计划 P0-P4 / 丢弃 / 审计员评分）并将 `external_audit:` YAML 合并到 Charter 遥测。 Agent 会在工作流的特定时刻**主动提议**审计 — 当实现完成、drift check 干净，且 `charter close` 尚未调用时。推荐基于 Charter 的风险面和复杂度给出 是/否（启发式见 `.devtrail/00-governance/AGENT-RULES.md` §12）。 diff --git a/docs/i18n/zh-CN/adopters/CLI-REFERENCE.md b/docs/i18n/zh-CN/adopters/CLI-REFERENCE.md index f2b4b32..f29211a 100644 --- a/docs/i18n/zh-CN/adopters/CLI-REFERENCE.md +++ b/docs/i18n/zh-CN/adopters/CLI-REFERENCE.md @@ -550,9 +550,9 @@ OK all declared-omitted paths are documented in AILOGs — drift accepted. 如果你运行的章程显式 scope 是治理 churn（例如仅触动 `.devtrail/07-ai-audit/` 的批量批准章程），漂移检查将报告 0 个修改文件，你需要通过阅读 AILOG 来验证 scope。一个 `--strict-scope` 标志（禁用"始终在 scope"规则）在桌面上，用于未来 minor 版本，前提是真实的 adopter 报告这种不对称为摩擦。 -#### `devtrail charter audit [--range ] [--calibrate | --finalize] [--path ]` +#### `devtrail charter audit [--range ] [--prepare | --merge-reports] [--merge-into ] [--path ]` -*自 **cli-3.8.0** + **fw-4.7.0** 起可用（Phase 3 v0）。* +*自 **cli-3.8.0** + **fw-4.7.0** 起可用。v1 统一流程在 **cli-3.10.0** + **fw-4.9.0** 中发布 — 用两步（PREPARE/MERGE-REPORTS）替换 v0 的三步（PREPARE/CALIBRATE/FINALIZE），统一审计员模板，并将规范路径迁移到 `.devtrail/audits/`。* 编排章程执行的多模型外部审计。**仅编排** — CLI 准备 prompts、根据 schema 验证 outputs，并打印可粘贴到章程遥测中的 findings。**它不调用 LLM API。** 操作员在自己选择的审计器（Copilot、Gemini、Claude 等）中运行 prompts，并将响应保存到规范路径。 @@ -1019,12 +1019,15 @@ 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+)* | 内联生成外部多模型审计 prompts。封装 `devtrail charter audit` PREPARE — 运行 CLI 解析 `auditor-primary.prompt.md` 与 `auditor-secondary.prompt.md`，并在对话中展示两个 prompts，操作员可粘贴到 2 个不同族的 LLM。 | `audit/charters//prompts/auditor-{primary,secondary}.prompt.md`（通过其封装的 CLI） | -| `/devtrail-audit-review CHARTER-ID` *(fw-4.8.0+)* | `/devtrail-audit-prompt` 的对应。验证操作员保存的审计员响应，内联运行校准器（驱动对话的 Agent 是有效的校准器，因为异质性仅对审计员对必需），并运行 `devtrail charter audit --finalize --merge-into` 直接将 `external_audit:` 追加到 `.devtrail/charters/.telemetry.yaml`。如果遥测尚不存在（Charter 未关闭），写入 `audit/charters//external-audit-pending.yaml` 供后续手动合并。 | `audit/charters//calibrator-reconciler.md`，`external_audit:` 数组合并入遥测 | +| `/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//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//report-.md` | +| `/devtrail-audit-review CHARTER-ID` *(fw-4.8.0+，在 fw-4.9.0 中扩展)* | `/devtrail-audit-prompt` 的对应。读取 `.devtrail/audits//` 下的 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//review.md`，`external_audit:` 数组合并入遥测（或 pending YAML） | ### Skill vs CLI -两个审计 skill 是 CLI 命令的**封装**。`audit/` 目录布局、prompts、schema 验证、`external_audit` 形状全部在 CLI 中 — skills 仅处理 UX-inline 部分（在对话中展示 prompts，内联运行校准器，触发合并）。不在循环中使用 AI 助手的 adopter 可直接通过 `devtrail charter audit`（PREPARE / `--calibrate` / `--finalize [--merge-into ]`）驱动相同工作流。 +三个审计 skill 是 CLI 命令和流程纪律的**封装**。`.devtrail/audits/` 下的规范路径、统一的 prompt 模板、schema 验证、`external_audit` 形状全部在 CLI + framework 中 — skills 处理 UX-inline 部分：调度操作员通过审计周期，无需手动管理文件。**操作员从不复制/粘贴 prompts 或 reports** — skills 通过 `.devtrail/audits/` 下的规范文件系统路径交换 artefacts。 + +不在循环中使用 AI 助手的 adopter 可直接通过 `devtrail charter audit`（`--prepare` / `--merge-reports [--merge-into ]`）驱动相同工作流。`.devtrail/audits//audit-prompt.md` 中的审计 prompt 在没有审计员 CLI 时也可粘贴到 chat 类 LLM 中使用 — skill 只是自动化文件交换。 ### 审计检查点 *(fw-4.8.0+)* diff --git a/docs/i18n/zh-CN/adopters/WORKFLOWS.md b/docs/i18n/zh-CN/adopters/WORKFLOWS.md index d47bb61..8ef8758 100644 --- a/docs/i18n/zh-CN/adopters/WORKFLOWS.md +++ b/docs/i18n/zh-CN/adopters/WORKFLOWS.md @@ -122,8 +122,9 @@ DevTrail 有两个文档系统： | `/devtrail-ailog` | 快速创建 AILOG | | `/devtrail-aidec` | 快速创建 AIDEC | | `/devtrail-adr` | 快速创建 ADR | -| `/devtrail-audit-prompt CHARTER-XX` *(fw-4.8.0+)* | 内联生成外部多模型审计 prompts。封装 `devtrail charter audit` PREPARE；在对话中展示两个审计员 prompts，操作员可粘贴到 2 个不同族的 LLM。 | -| `/devtrail-audit-review CHARTER-XX` *(fw-4.8.0+)* | `audit-prompt` 的对应。验证审计员响应，内联运行校准器，并通过 `--merge-into` 将 findings 合并到 Charter 遥测。 | +| `/devtrail-audit-prompt CHARTER-XX` *(fw-4.8.0+，在 fw-4.9.0 中重构)* | 在规范路径 `.devtrail/audits//audit-prompt.md` 处生成统一的审计 prompt。封装 `devtrail charter audit --prepare`。操作员随后打开 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。参数可选 — 自动发现此模型待处理的 prompts。 | +| `/devtrail-audit-review CHARTER-XX` *(fw-4.8.0+，在 fw-4.9.0 中扩展)* | `audit-prompt` 的对应。读取 N 个 reports，对 findings 与实际代码交叉验证，生成 `review.md` 六节合并分析（执行摘要 / 范围 / 按审计员评估 / 修复计划 P0-P4 / 丢弃 / 审计员评分），并将 `external_audit:` YAML 合并到遥测。 | 完整 Skill 详情参见 [README](../README.md#skills)。