diff --git a/cli/tests/audit_skill_test.rs b/cli/tests/audit_skill_test.rs index 2ee97c3..2de88df 100644 --- a/cli/tests/audit_skill_test.rs +++ b/cli/tests/audit_skill_test.rs @@ -239,3 +239,157 @@ fn devtrail_audit_review_three_platforms_share_core_guidance() { ); } } + +// ── devtrail-audit-execute (PR 5 — v1 audit-skills) ──────────────────────── + +#[test] +fn devtrail_audit_execute_claude_skill_exists_and_has_allowed_tools() { + let body = read( + dist_root() + .join(".claude") + .join("skills") + .join("devtrail-audit-execute") + .join("SKILL.md"), + ); + assert!(body.starts_with("---\n"), "missing YAML frontmatter"); + assert!( + body.contains("name: devtrail-audit-execute"), + "missing name field" + ); + assert!( + body.contains("allowed-tools:"), + "Claude skill must declare allowed-tools" + ); + // The skill orchestrates audit execution with tool use; common build/test + // commands across stacks should be allowlisted. + assert!( + body.contains("go vet") + && body.contains("cargo") + && body.contains("npm") + && body.contains("pytest"), + "allowed-tools should permit common build/test commands across stacks" + ); + assert!( + body.contains("argument-hint:"), + "Claude skill should declare argument-hint for the optional CHARTER-NN arg" + ); +} + +#[test] +fn devtrail_audit_execute_gemini_skill_exists_without_allowed_tools() { + let body = read( + dist_root() + .join(".gemini") + .join("skills") + .join("devtrail-audit-execute") + .join("SKILL.md"), + ); + assert!(body.starts_with("---\n"), "missing YAML frontmatter"); + assert!( + body.contains("name: devtrail-audit-execute"), + "missing name field" + ); + assert!( + !body.contains("allowed-tools:"), + "Gemini skill must not declare allowed-tools" + ); +} + +#[test] +fn devtrail_audit_execute_agent_workflow_exists_with_description_only() { + let body = read( + dist_root() + .join(".agent") + .join("workflows") + .join("devtrail-audit-execute.md"), + ); + assert!(body.starts_with("---\n"), "missing YAML frontmatter"); + assert!( + !body.contains("name:"), + "agent workflow must not declare a name field" + ); + assert!( + !body.contains("allowed-tools:"), + "agent workflow must not declare allowed-tools" + ); + assert!( + body.contains("description:"), + "agent workflow must declare description" + ); +} + +#[test] +fn devtrail_audit_execute_three_platforms_share_core_guidance() { + let claude = read( + dist_root() + .join(".claude") + .join("skills") + .join("devtrail-audit-execute") + .join("SKILL.md"), + ); + let gemini = read( + dist_root() + .join(".gemini") + .join("skills") + .join("devtrail-audit-execute") + .join("SKILL.md"), + ); + let agent = read( + dist_root() + .join(".agent") + .join("workflows") + .join("devtrail-audit-execute.md"), + ); + + for body in [&claude, &gemini, &agent] { + // Canonical paths the skill uses. + assert!( + body.contains(".devtrail/audits/"), + "skill must reference the v1 canonical audit dir" + ); + assert!( + body.contains("audit-prompt.md"), + "skill must read the unified audit prompt" + ); + assert!( + body.contains("report-.md") + || body.contains("report-.md"), + "skill must write the report at the keyed path" + ); + + // D14: discovery automático when arg omitted. + assert!( + body.contains("argument is optional") + || body.contains("argument provided") + || body.contains("arg omitted") + || body.contains("Auto-discover"), + "skill must handle the optional-argument auto-discovery case" + ); + + // D14: model-slug detection. + assert!( + body.contains("model identifier") && body.contains("slug"), + "skill must explain how to detect and slugify the model identifier" + ); + + // The wait warning — load-bearing for parallel-CLI workflows. + assert!( + body.contains("ALL audits") && body.contains("complete"), + "skill must warn the operator to wait for ALL commissioned audits before invoking review" + ); + assert!( + body.contains("/devtrail-audit-review"), + "skill must point at the audit-review skill as the next step" + ); + + // Discipline carried from the prompt template. + assert!( + body.contains("path:line"), + "skill must reference the path:line citation discipline" + ); + assert!( + body.contains("Read-only") || body.contains("read-only"), + "skill must reinforce the read-only constraint" + ); + } +} diff --git a/dist/.agent/workflows/devtrail-audit-execute.md b/dist/.agent/workflows/devtrail-audit-execute.md new file mode 100644 index 0000000..317e696 --- /dev/null +++ b/dist/.agent/workflows/devtrail-audit-execute.md @@ -0,0 +1,150 @@ +--- +description: Execute an external audit of a Charter inside an auditor-side CLI (gemini-cli, claude-cli, copilot-cli, codex-cli). Reads the resolved audit prompt from the canonical location, audits with tool use, writes the report. Operator invokes one instance per CLI. +--- + +# DevTrail Audit Execute Skill + +Execute an external audit of a Charter inside this CLI session. Read the resolved audit prompt that DevTrail prepared at the canonical location, audit the implementation with tool use (citing `path:line` of files actually opened), and write the report at the canonical location for the audit-review skill to consolidate later. + +## When to invoke + +This skill runs **inside an auditor-side CLI** (gemini-cli, claude-cli, copilot-cli, codex-cli, or any agent runtime configured with read-only access to the adopter's repo). The operator opens the CLI in the repo, then invokes `/devtrail-audit-execute `. + +The skill is the second step of the v1 audit cycle: + +1. In the main IDE: operator runs `/devtrail-audit-prompt CHARTER-NN` → DevTrail writes `.devtrail/audits/CHARTER-NN/audit-prompt.md`. +2. **(this skill)** Operator opens an auditor-side CLI in the repo and runs `/devtrail-audit-execute CHARTER-NN`. Repeat in N CLIs (recommended: ≥2 of different model families). +3. When ALL audits commissioned have completed, operator returns to the main IDE and runs `/devtrail-audit-review CHARTER-NN`. + +## Instructions + +### 1. Resolve the Charter + +The argument is optional. Two cases: + +**Case A — argument provided** (`/devtrail-audit-execute CHARTER-04`): +Use the literal value. Construct the audit dir path: `.devtrail/audits/CHARTER-04/`. + +**Case B — argument omitted** (`/devtrail-audit-execute`): +Auto-discover pending prompts. Detect this auditor's model identifier (see step 2 for how) and produce its slug. Then: + +```bash +# List all audit prompts that exist +ls .devtrail/audits/*/audit-prompt.md 2>/dev/null +``` + +For each found `.devtrail/audits//audit-prompt.md`, check whether a report from this model already exists at `.devtrail/audits//report-.md`. The set of "pending" prompts is the ones WITHOUT a corresponding report. + +- **Exactly one pending** → proceed with that CHARTER-ID, announcing the choice to the operator. +- **Multiple pending** → list them numerically with their Charter titles (read the title from the resolved prompt's `# Auditoría de Charter — CHARTER-NN` heading) and ask the operator to pick one. +- **None pending** → message: "No pending audit prompts for this model under `.devtrail/audits/`. Either the operator has not run `/devtrail-audit-prompt` in the main agent yet, or all the prompts already have a report from this model. Verify with the operator." + +### 2. Detect this auditor's model identifier + +Identify the model running this CLI session and produce a filesystem-safe slug. + +The operator will know the canonical model id of the auditor running this skill (for example `claude-sonnet-4-6`, `claude-opus-4-7`, `gemini-2.5-pro`, `gpt-5.3-codex`, `copilot-v1.0.40`). Slug rules: + +- Lowercase ASCII. +- Replace any character that isn't `[a-z0-9-]` with `-`. +- Collapse consecutive dashes to one. +- Trim leading/trailing dashes. + +Examples: + +| Model identifier | Slug | +|---|---| +| `claude-sonnet-4-6` | `claude-sonnet-4-6` | +| `gemini-2.5-pro` | `gemini-2-5-pro` | +| `gpt-5.3-codex` | `gpt-5-3-codex` | +| `copilot-v1.0.40` | `copilot-v1-0-40` | + +If the runtime does not expose the model identifier directly, ask the operator to confirm before proceeding. Do NOT fabricate a slug — collisions or wrong identifiers corrupt the review step. + +### 3. Read the audit prompt + +```bash +cat .devtrail/audits//audit-prompt.md +``` + +The prompt is self-contained: it includes the Charter content, originating AILOGs, git diff, and the discipline rules (REGLA ABSOLUTA — SOLO LECTURA, evidence-citation discipline, severity calibration). Read it carefully before auditing. + +### 4. Audit with tool use + +Follow the prompt literally, with these expectations: + +- **Read-only**: never write to project files. The only output you are allowed to produce is the report at the canonical path in step 5. +- **Tool-use evidence**: every finding you record must cite `path:line` of files you actually opened via `Read`, `Grep`, or equivalent. Do not infer behavior from file names alone. +- **Severity calibration**: open the active configuration (factories, env defaults, build tags, deployment scaling) before declaring Critical/High severity. The Etapa 12 example in the prompt is a real case of inflation that the calibration discipline catches. +- **Scope discipline**: only report findings inside the Charter's declared scope. Out-of-scope observations go in their own section, not as defects. + +Track how many `path:line` citations you accumulate — it goes in the report frontmatter as `evidence_citations`. + +### 5. Write the report + +Output path: + +``` +.devtrail/audits//report-.md +``` + +If a report at that exact path already exists (re-run on the same Charter with the same model), warn the operator before overwriting. The default is to overwrite — re-runs replace stale reports rather than coexist with them. + +If, by some unusual reason, two distinct sessions of the SAME model audited the same Charter and the operator wants both, append a numeric suffix manually: `report--2.md`. + +The report frontmatter MUST conform to `audit-output.schema.v0.json`: + +```yaml +--- +audit_role: auditor +auditor: # e.g., claude-sonnet-4-6 +charter_id: +git_range: "" +prompt_used: audit-prompt.md +audited_at: +findings_total: +findings_by_category: + hallucination: + implementation_gap: + real_debt: + false_positive: +evidence_citations: # how many path:line citations the body contains +audit_quality: high | medium | low +--- + +# (body following the format declared in the prompt's "Formato de salida" section) +``` + +### 6. Notify the operator — with the wait warning + +After writing the report, print this message verbatim (substituting ``, ``, and the finding count): + +``` +Audit complete for (this auditor: ). + + Report: .devtrail/audits//report-.md + Findings: total () + +IMPORTANT: do NOT return to the main agent for /devtrail-audit-review yet +unless ALL audits you commissioned have completed. + +If you opened other auditor CLIs (gemini-cli, copilot-cli, codex-cli, ...) +and have not yet seen their /devtrail-audit-execute finish, wait for them. +Invoking /devtrail-audit-review with incomplete reports produces a partial +consolidated analysis that you will have to discard or re-run — costing +you the audit cycle. + +When and only when ALL audits you commissioned are complete, return to +your main IDE and run: + + /devtrail-audit-review +``` + +This wait warning matters: an operator with three CLIs open in parallel can be tempted to invoke review as soon as the first audit finishes. The review skill iterates whatever reports are present at the time it runs; it cannot wait for additional reports to arrive. + +## Notes + +- **No HTTP API calls.** This skill runs inside an auditor CLI that the operator chose; that CLI handles all model invocation, API keys, and rate limits. DevTrail orchestrates prompt resolution and report shape — nothing else. +- **Re-runs**: if you invoke this skill on a Charter whose report from this model already exists, the existing one is overwritten. The previous report is lost — if you wanted to keep it, copy it manually before re-running. +- **Multiple Charters in the same CLI session**: invoke the skill once per Charter. Reports do not collide because the filename is keyed on Charter id + model slug. +- **Heterogeneity inter-family**: the skill does not enforce that the operator uses different model families across the N audit-execute invocations. The recommendation is in the audit prompt itself and in `AGENT-RULES.md` §12; trust the operator. diff --git a/dist/.claude/skills/devtrail-audit-execute/SKILL.md b/dist/.claude/skills/devtrail-audit-execute/SKILL.md new file mode 100644 index 0000000..f84e618 --- /dev/null +++ b/dist/.claude/skills/devtrail-audit-execute/SKILL.md @@ -0,0 +1,153 @@ +--- +name: devtrail-audit-execute +description: Execute an external audit of a Charter inside an auditor-side CLI (gemini-cli, claude-cli, copilot-cli, codex-cli). Reads the resolved audit prompt from the canonical location, audits with tool use, writes the report. Operator invokes one instance per CLI. +allowed-tools: Read, Write, Glob, Grep, Bash(go vet *, go build *, go test *, cargo check *, cargo clippy *, cargo test --no-run, npm run lint, npm run typecheck, npm test --, pytest --co, mypy *, ruff check *, ls *, find *, wc *, git log *, git diff *, git status *) +argument-hint: "CHARTER-NN (optional — auto-discovers pending prompts)" +--- + +# DevTrail Audit Execute Skill + +Execute an external audit of a Charter inside this CLI session. Read the resolved audit prompt that DevTrail prepared at the canonical location, audit the implementation with tool use (citing `path:line` of files actually opened), and write the report at the canonical location for the audit-review skill to consolidate later. + +## When to invoke + +This skill runs **inside an auditor-side CLI** (gemini-cli, claude-cli, copilot-cli, codex-cli, or any agent runtime configured with read-only access to the adopter's repo). The operator opens the CLI in the repo, then invokes `/devtrail-audit-execute `. + +The skill is the second step of the v1 audit cycle: + +1. In the main IDE: operator runs `/devtrail-audit-prompt CHARTER-NN` → DevTrail writes `.devtrail/audits/CHARTER-NN/audit-prompt.md`. +2. **(this skill)** Operator opens an auditor-side CLI in the repo and runs `/devtrail-audit-execute CHARTER-NN`. Repeat in N CLIs (recommended: ≥2 of different model families). +3. When ALL audits commissioned have completed, operator returns to the main IDE and runs `/devtrail-audit-review CHARTER-NN`. + +## Instructions + +### 1. Resolve the Charter + +The argument is optional. Two cases: + +**Case A — argument provided** (`/devtrail-audit-execute CHARTER-04`): +Use the literal value. Construct the audit dir path: `.devtrail/audits/CHARTER-04/`. + +**Case B — argument omitted** (`/devtrail-audit-execute`): +Auto-discover pending prompts. Detect this auditor's model identifier (see step 2 for how) and produce its slug. Then: + +```bash +# List all audit prompts that exist +ls .devtrail/audits/*/audit-prompt.md 2>/dev/null +``` + +For each found `.devtrail/audits//audit-prompt.md`, check whether a report from this model already exists at `.devtrail/audits//report-.md`. The set of "pending" prompts is the ones WITHOUT a corresponding report. + +- **Exactly one pending** → proceed with that CHARTER-ID, announcing the choice to the operator. +- **Multiple pending** → list them numerically with their Charter titles (read the title from the resolved prompt's `# Auditoría de Charter — CHARTER-NN` heading) and ask the operator to pick one. +- **None pending** → message: "No pending audit prompts for this model under `.devtrail/audits/`. Either the operator has not run `/devtrail-audit-prompt` in the main agent yet, or all the prompts already have a report from this model. Verify with the operator." + +### 2. Detect this auditor's model identifier + +Identify the model running this CLI session and produce a filesystem-safe slug. + +The operator will know the canonical model id of the auditor running this skill (for example `claude-sonnet-4-6`, `claude-opus-4-7`, `gemini-2.5-pro`, `gpt-5.3-codex`, `copilot-v1.0.40`). Slug rules: + +- Lowercase ASCII. +- Replace any character that isn't `[a-z0-9-]` with `-`. +- Collapse consecutive dashes to one. +- Trim leading/trailing dashes. + +Examples: + +| Model identifier | Slug | +|---|---| +| `claude-sonnet-4-6` | `claude-sonnet-4-6` | +| `gemini-2.5-pro` | `gemini-2-5-pro` | +| `gpt-5.3-codex` | `gpt-5-3-codex` | +| `copilot-v1.0.40` | `copilot-v1-0-40` | + +If the runtime does not expose the model identifier directly, ask the operator to confirm before proceeding. Do NOT fabricate a slug — collisions or wrong identifiers corrupt the review step. + +### 3. Read the audit prompt + +```bash +cat .devtrail/audits//audit-prompt.md +``` + +The prompt is self-contained: it includes the Charter content, originating AILOGs, git diff, and the discipline rules (REGLA ABSOLUTA — SOLO LECTURA, evidence-citation discipline, severity calibration). Read it carefully before auditing. + +### 4. Audit with tool use + +Follow the prompt literally, with these expectations: + +- **Read-only**: never write to project files. The only output you are allowed to produce is the report at the canonical path in step 5. +- **Tool-use evidence**: every finding you record must cite `path:line` of files you actually opened via `Read`, `Grep`, or equivalent. Do not infer behavior from file names alone. +- **Severity calibration**: open the active configuration (factories, env defaults, build tags, deployment scaling) before declaring Critical/High severity. The Etapa 12 example in the prompt is a real case of inflation that the calibration discipline catches. +- **Scope discipline**: only report findings inside the Charter's declared scope. Out-of-scope observations go in their own section, not as defects. + +Track how many `path:line` citations you accumulate — it goes in the report frontmatter as `evidence_citations`. + +### 5. Write the report + +Output path: + +``` +.devtrail/audits//report-.md +``` + +If a report at that exact path already exists (re-run on the same Charter with the same model), warn the operator before overwriting. The default is to overwrite — re-runs replace stale reports rather than coexist with them. + +If, by some unusual reason, two distinct sessions of the SAME model audited the same Charter and the operator wants both, append a numeric suffix manually: `report--2.md`. + +The report frontmatter MUST conform to `audit-output.schema.v0.json`: + +```yaml +--- +audit_role: auditor +auditor: # e.g., claude-sonnet-4-6 +charter_id: +git_range: "" +prompt_used: audit-prompt.md +audited_at: +findings_total: +findings_by_category: + hallucination: + implementation_gap: + real_debt: + false_positive: +evidence_citations: # how many path:line citations the body contains +audit_quality: high | medium | low +--- + +# (body following the format declared in the prompt's "Formato de salida" section) +``` + +### 6. Notify the operator — with the wait warning + +After writing the report, print this message verbatim (substituting ``, ``, and the finding count): + +``` +Audit complete for (this auditor: ). + + Report: .devtrail/audits//report-.md + Findings: total () + +IMPORTANT: do NOT return to the main agent for /devtrail-audit-review yet +unless ALL audits you commissioned have completed. + +If you opened other auditor CLIs (gemini-cli, copilot-cli, codex-cli, ...) +and have not yet seen their /devtrail-audit-execute finish, wait for them. +Invoking /devtrail-audit-review with incomplete reports produces a partial +consolidated analysis that you will have to discard or re-run — costing +you the audit cycle. + +When and only when ALL audits you commissioned are complete, return to +your main IDE and run: + + /devtrail-audit-review +``` + +This wait warning matters: an operator with three CLIs open in parallel can be tempted to invoke review as soon as the first audit finishes. The review skill iterates whatever reports are present at the time it runs; it cannot wait for additional reports to arrive. + +## Notes + +- **No HTTP API calls.** This skill runs inside an auditor CLI that the operator chose; that CLI handles all model invocation, API keys, and rate limits. DevTrail orchestrates prompt resolution and report shape — nothing else. +- **Re-runs**: if you invoke this skill on a Charter whose report from this model already exists, the existing one is overwritten. The previous report is lost — if you wanted to keep it, copy it manually before re-running. +- **Multiple Charters in the same CLI session**: invoke the skill once per Charter. Reports do not collide because the filename is keyed on Charter id + model slug. +- **Heterogeneity inter-family**: the skill does not enforce that the operator uses different model families across the N audit-execute invocations. The recommendation is in the audit prompt itself and in `AGENT-RULES.md` §12; trust the operator. diff --git a/dist/.gemini/skills/devtrail-audit-execute/SKILL.md b/dist/.gemini/skills/devtrail-audit-execute/SKILL.md new file mode 100644 index 0000000..c38a676 --- /dev/null +++ b/dist/.gemini/skills/devtrail-audit-execute/SKILL.md @@ -0,0 +1,151 @@ +--- +name: devtrail-audit-execute +description: Execute an external audit of a Charter inside an auditor-side CLI (gemini-cli, claude-cli, copilot-cli, codex-cli). Reads the resolved audit prompt from the canonical location, audits with tool use, writes the report. Operator invokes one instance per CLI. +--- + +# DevTrail Audit Execute Skill + +Execute an external audit of a Charter inside this CLI session. Read the resolved audit prompt that DevTrail prepared at the canonical location, audit the implementation with tool use (citing `path:line` of files actually opened), and write the report at the canonical location for the audit-review skill to consolidate later. + +## When to invoke + +This skill runs **inside an auditor-side CLI** (gemini-cli, claude-cli, copilot-cli, codex-cli, or any agent runtime configured with read-only access to the adopter's repo). The operator opens the CLI in the repo, then invokes `/devtrail-audit-execute `. + +The skill is the second step of the v1 audit cycle: + +1. In the main IDE: operator runs `/devtrail-audit-prompt CHARTER-NN` → DevTrail writes `.devtrail/audits/CHARTER-NN/audit-prompt.md`. +2. **(this skill)** Operator opens an auditor-side CLI in the repo and runs `/devtrail-audit-execute CHARTER-NN`. Repeat in N CLIs (recommended: ≥2 of different model families). +3. When ALL audits commissioned have completed, operator returns to the main IDE and runs `/devtrail-audit-review CHARTER-NN`. + +## Instructions + +### 1. Resolve the Charter + +The argument is optional. Two cases: + +**Case A — argument provided** (`/devtrail-audit-execute CHARTER-04`): +Use the literal value. Construct the audit dir path: `.devtrail/audits/CHARTER-04/`. + +**Case B — argument omitted** (`/devtrail-audit-execute`): +Auto-discover pending prompts. Detect this auditor's model identifier (see step 2 for how) and produce its slug. Then: + +```bash +# List all audit prompts that exist +ls .devtrail/audits/*/audit-prompt.md 2>/dev/null +``` + +For each found `.devtrail/audits//audit-prompt.md`, check whether a report from this model already exists at `.devtrail/audits//report-.md`. The set of "pending" prompts is the ones WITHOUT a corresponding report. + +- **Exactly one pending** → proceed with that CHARTER-ID, announcing the choice to the operator. +- **Multiple pending** → list them numerically with their Charter titles (read the title from the resolved prompt's `# Auditoría de Charter — CHARTER-NN` heading) and ask the operator to pick one. +- **None pending** → message: "No pending audit prompts for this model under `.devtrail/audits/`. Either the operator has not run `/devtrail-audit-prompt` in the main agent yet, or all the prompts already have a report from this model. Verify with the operator." + +### 2. Detect this auditor's model identifier + +Identify the model running this CLI session and produce a filesystem-safe slug. + +The operator will know the canonical model id of the auditor running this skill (for example `claude-sonnet-4-6`, `claude-opus-4-7`, `gemini-2.5-pro`, `gpt-5.3-codex`, `copilot-v1.0.40`). Slug rules: + +- Lowercase ASCII. +- Replace any character that isn't `[a-z0-9-]` with `-`. +- Collapse consecutive dashes to one. +- Trim leading/trailing dashes. + +Examples: + +| Model identifier | Slug | +|---|---| +| `claude-sonnet-4-6` | `claude-sonnet-4-6` | +| `gemini-2.5-pro` | `gemini-2-5-pro` | +| `gpt-5.3-codex` | `gpt-5-3-codex` | +| `copilot-v1.0.40` | `copilot-v1-0-40` | + +If the runtime does not expose the model identifier directly, ask the operator to confirm before proceeding. Do NOT fabricate a slug — collisions or wrong identifiers corrupt the review step. + +### 3. Read the audit prompt + +```bash +cat .devtrail/audits//audit-prompt.md +``` + +The prompt is self-contained: it includes the Charter content, originating AILOGs, git diff, and the discipline rules (REGLA ABSOLUTA — SOLO LECTURA, evidence-citation discipline, severity calibration). Read it carefully before auditing. + +### 4. Audit with tool use + +Follow the prompt literally, with these expectations: + +- **Read-only**: never write to project files. The only output you are allowed to produce is the report at the canonical path in step 5. +- **Tool-use evidence**: every finding you record must cite `path:line` of files you actually opened via `Read`, `Grep`, or equivalent. Do not infer behavior from file names alone. +- **Severity calibration**: open the active configuration (factories, env defaults, build tags, deployment scaling) before declaring Critical/High severity. The Etapa 12 example in the prompt is a real case of inflation that the calibration discipline catches. +- **Scope discipline**: only report findings inside the Charter's declared scope. Out-of-scope observations go in their own section, not as defects. + +Track how many `path:line` citations you accumulate — it goes in the report frontmatter as `evidence_citations`. + +### 5. Write the report + +Output path: + +``` +.devtrail/audits//report-.md +``` + +If a report at that exact path already exists (re-run on the same Charter with the same model), warn the operator before overwriting. The default is to overwrite — re-runs replace stale reports rather than coexist with them. + +If, by some unusual reason, two distinct sessions of the SAME model audited the same Charter and the operator wants both, append a numeric suffix manually: `report--2.md`. + +The report frontmatter MUST conform to `audit-output.schema.v0.json`: + +```yaml +--- +audit_role: auditor +auditor: # e.g., claude-sonnet-4-6 +charter_id: +git_range: "" +prompt_used: audit-prompt.md +audited_at: +findings_total: +findings_by_category: + hallucination: + implementation_gap: + real_debt: + false_positive: +evidence_citations: # how many path:line citations the body contains +audit_quality: high | medium | low +--- + +# (body following the format declared in the prompt's "Formato de salida" section) +``` + +### 6. Notify the operator — with the wait warning + +After writing the report, print this message verbatim (substituting ``, ``, and the finding count): + +``` +Audit complete for (this auditor: ). + + Report: .devtrail/audits//report-.md + Findings: total () + +IMPORTANT: do NOT return to the main agent for /devtrail-audit-review yet +unless ALL audits you commissioned have completed. + +If you opened other auditor CLIs (gemini-cli, copilot-cli, codex-cli, ...) +and have not yet seen their /devtrail-audit-execute finish, wait for them. +Invoking /devtrail-audit-review with incomplete reports produces a partial +consolidated analysis that you will have to discard or re-run — costing +you the audit cycle. + +When and only when ALL audits you commissioned are complete, return to +your main IDE and run: + + /devtrail-audit-review +``` + +This wait warning matters: an operator with three CLIs open in parallel can be tempted to invoke review as soon as the first audit finishes. The review skill iterates whatever reports are present at the time it runs; it cannot wait for additional reports to arrive. + +## Notes + +- **No HTTP API calls.** This skill runs inside an auditor CLI that the operator chose; that CLI handles all model invocation, API keys, and rate limits. DevTrail orchestrates prompt resolution and report shape — nothing else. +- **Re-runs**: if you invoke this skill on a Charter whose report from this model already exists, the existing one is overwritten. The previous report is lost — if you wanted to keep it, copy it manually before re-running. +- **Multiple Charters in the same CLI session**: invoke the skill once per Charter. Reports do not collide because the filename is keyed on Charter id + model slug. +- **Heterogeneity inter-family**: the skill does not enforce that the operator uses different model families across the N audit-execute invocations. The recommendation is in the audit prompt itself and in `AGENT-RULES.md` §12; trust the operator.