You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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) <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: dist/.devtrail/00-governance/AGENT-RULES.md
+12-6Lines changed: 12 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -301,11 +301,17 @@ My recommendation: [YES / NO], because:
301
301
- <one specific reason grounded in the Charter, AILOGs, or diff>
302
302
303
303
If you decide to audit:
304
-
Run /devtrail-audit-prompt <CHARTER-ID> and I will surface the two
305
-
prompts inline. Once you have the responses from the external
306
-
auditors saved to canonical paths, run /devtrail-audit-review
307
-
<CHARTER-ID> and I will calibrate them locally and merge the
308
-
findings into the Charter telemetry.
304
+
Run /devtrail-audit-prompt <CHARTER-ID> and I will write the unified
305
+
audit prompt to .devtrail/audits/<CHARTER-ID>/audit-prompt.md.
306
+
Then open one or more auditor-side CLIs (gemini-cli, claude-cli,
307
+
copilot-cli, codex-cli) in this repo and invoke
308
+
/devtrail-audit-execute <CHARTER-ID> in each — recommendation: at
309
+
least 2 auditors of different model families. When and only when
310
+
ALL auditors you commissioned have completed, return here and run
311
+
/devtrail-audit-review <CHARTER-ID>. I will consolidate the N
312
+
reports into a review.md document with verdicts, remediation plan,
313
+
and auditor ratings, and merge the YAML block into the Charter
314
+
telemetry.
309
315
310
316
If you decide not to audit:
311
317
Continue with `devtrail charter close <CHARTER-ID>` when you're
@@ -341,7 +347,7 @@ These are heuristics, not rigid rules — you are close to the context, refine t
341
347
- The checkpoint is **never** repeated within the same Charter once the developer responds.
342
348
- 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).
343
349
- 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.
344
-
- If the developer accepts the audit, the next two skills (`/devtrail-audit-prompt` then `/devtrail-audit-review`) carry the workflow forward.
350
+
- 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/<id>/review.md` and merges the YAML into telemetry). Operators never copy/paste prompts or reports — file exchange happens via canonical paths under `.devtrail/audits/`.
|`/devtrail-audit-review CHARTER-XX`*(fw-4.8.0+)*| Calibrate audit responses + merge into Charter telemetry |
216
+
|`/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 |
217
+
|`/devtrail-audit-execute [CHARTER-XX]`*(fw-4.9.0+)*| Run inside an auditor CLI — read prompt, audit with tool use, write report |
218
+
|`/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 |
Copy file name to clipboardExpand all lines: dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md
+12-6Lines changed: 12 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -301,11 +301,17 @@ Mi recomendación: [SÍ / NO], porque:
301
301
- <razón concreta basada en el Charter, AILOGs o diff>
302
302
303
303
Si decides auditar:
304
-
Ejecuta /devtrail-audit-prompt <CHARTER-ID> y te imprimo aquí mismo
305
-
los dos prompts. Cuando tengas las respuestas de los auditores externos
306
-
guardadas en los paths canónicos, ejecuta /devtrail-audit-review
307
-
<CHARTER-ID> y yo calibro localmente y mergeo los findings en la
308
-
telemetría del Charter.
304
+
Ejecuta /devtrail-audit-prompt <CHARTER-ID> y yo escribo el prompt
305
+
unificado de auditoría en .devtrail/audits/<CHARTER-ID>/audit-prompt.md.
306
+
Después abre una o más CLIs auditoras (gemini-cli, claude-cli,
307
+
copilot-cli, codex-cli) en este repo e invoca
308
+
/devtrail-audit-execute <CHARTER-ID> en cada una — recomendación: al
309
+
menos 2 auditores de familias de modelo distintas. Cuando y solo
310
+
cuando TODAS las auditorías que encargaste hayan terminado, regresa
311
+
aquí y ejecuta /devtrail-audit-review <CHARTER-ID>. Yo consolido los
312
+
N reports en un documento review.md con veredictos, plan de
313
+
remediación y calificación de auditores, y mergeo el bloque YAML en
314
+
la telemetría del Charter.
309
315
310
316
Si decides no auditar:
311
317
Continúa con `devtrail charter close <CHARTER-ID>` cuando estés listo.
@@ -341,7 +347,7 @@ Son heurísticas, no reglas rígidas — estás cerca del contexto, afínalas co
341
347
- El checkpoint **nunca** se repite dentro del mismo Charter una vez que el developer responde.
342
348
- 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).
343
349
- 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.
344
-
- Si el developer acepta la auditoría, las siguientes dos skills (`/devtrail-audit-prompt` luego `/devtrail-audit-review`) llevan el workflow adelante.
350
+
- 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/<id>/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/`.
Copy file name to clipboardExpand all lines: docs/adopters/ADOPTION-GUIDE.md
+3-2Lines changed: 3 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -502,8 +502,9 @@ devtrail validate
502
502
503
503
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:
504
504
505
-
-**`/devtrail-audit-prompt CHARTER-XX`** — generates the auditor prompts inline in the conversation, ready to paste into 2 LLM auditors of different families.
506
-
-**`/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).
505
+
-**`/devtrail-audit-prompt CHARTER-XX`** — writes the unified audit prompt at the canonical path `.devtrail/audits/<id>/audit-prompt.md`. Operator opens N auditor-side CLIs and runs `/devtrail-audit-execute` in each. No copy/paste.
506
+
-**`/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.
507
+
-**`/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.
507
508
508
509
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).
0 commit comments