Conversation
… paths
Closes the CLI side of the v1 audit-skills iteration described in
Propuesta/devtrail-audit-cli-flow.md v0.2 §3.2 + §5.1 PR 4. This is
the largest refactor of the rollout: switches `devtrail charter audit`
from the v0 three-step subcommand (PREPARE/CALIBRATE/FINALIZE with
two auditor templates + calibrator template) to the v1 unified flow
(PREPARE writes one prompt; the operator runs N auditors via the new
audit-execute skill in PR 5; merge-reports validates N reports and
emits/merges the YAML; the calibrator role moves to the main agent
via the audit-review skill in PR 6).
Subcommand changes (cli/src/main.rs):
- NEW flag --prepare (default action): generates the unified
audit-prompt at the canonical path. Mutually exclusive with the
other action flags via clap's conflicts_with_all.
- NEW flag --merge-reports: reads N report-*.md from the canonical
audit dir, validates each against audit-output.schema.v0.json,
emits the external_audit YAML (or merges into telemetry with
--merge-into).
- --merge-into now combines with --merge-reports (or the deprecated
--finalize for backwards compat). Removed `requires = "finalize"`.
- DEPRECATED --calibrate: kept for backwards compat (hidden in
--help via #[arg(hide = true)]). Emits a warning explaining the
v1 flow has no separate calibrate step (the main agent fills the
calibrator role inline via /devtrail-audit-review skill) and
exits with error.
- DEPRECATED --finalize: hidden alias for --merge-reports. Emits a
warning and routes through the new path. Functional equivalent
when reports exist at the canonical location.
Canonical path migration (cli/src/commands/charter/audit.rs):
- audit_dir is now .devtrail/audits/<CHARTER-ID>/ (was
audit/charters/<CHARTER-ID>/). Per Propuesta D13: the new
location is namespaced under .devtrail/ to avoid collisions
with adopter-defined audit/ folders, and the structure leaves
the door open for future audit-unit categories beyond Charter
(MODULE-, RELEASE-, EPIC-, etc.) without restructuring.
- The unified audit-prompt is written to <audit_dir>/audit-prompt.md
(single file, not a prompts/ subdirectory with two files).
- Reports land at <audit_dir>/report-<sluggified-model-id>.md (the
v1 audit-execute skill in PR 5 will produce these; manual paste
is also supported).
Resolver simplification:
- run_prepare reads ONE template (audit-prompt.md) and writes ONE
resolved file. The two-pass loop over auditor-primary/secondary
is gone.
- run_calibrate REMOVED (replaced by deprecation shim that emits
a warning and exits).
- run_finalize REPLACED by run_merge_reports, which globs
report-*.md instead of reading two fixed paths. Iterates over
N>=1 reports; warns when only one is present (heterogeneity
inter-family is the discovery mechanism); errors when none
found with helpful message about running --prepare first or
invoking the audit-execute skill.
- AuditContext: dropped auditor_primary_findings and
auditor_secondary_findings (only used by the now-deleted
calibrator template). NEW field project_context (D12) for the
{{project_context}} placeholder; default empty until adopters
fill it manually or a future release derives it from
CLAUDE.md / config.yml.
- resolve_audit_template's pairs array shrunk by 2 placeholders
(auditor_primary_findings, auditor_secondary_findings) and
grew by 1 ({{project_context}}). Net: 12 → 11 placeholders.
Templates deleted (PR 3 already shipped the unified replacement):
- dist/.devtrail/audit-prompts/auditor-primary.md (154 lines)
- dist/.devtrail/audit-prompts/auditor-secondary.md (131 lines)
- dist/.devtrail/audit-prompts/calibrator-reconciler.md (173 lines)
Only audit-prompt.md remains in dist/.devtrail/audit-prompts/.
Tests (cli/tests/charter_audit_test.rs): rewritten extensively.
- setup_devtrail simplified: writes only audit-prompt.md (no
primary/secondary/calibrator).
- NEW helper audit_dir(dir, charter_id) returns the v1 canonical
path.
- setup_finalized_audit writes two reports under the canonical
path with audit_role: auditor (v1 unified).
- REMOVED tests that assumed the v0 three-step flow:
audit_calibrate_requires_auditor_outputs,
audit_calibrate_validates_outputs_against_schema,
audit_full_three_step_cycle_succeeds,
audit_calibrate_and_finalize_are_mutually_exclusive.
- REPLACED with v1 equivalents:
audit_merge_reports_with_no_reports_fails_helpfully,
audit_merge_reports_validates_against_schema,
audit_merge_reports_handles_n_reports_with_unified_role
(exercises N=3 reports with audit_role: auditor),
audit_merge_reports_warns_on_single_report_but_proceeds,
audit_deprecated_calibrate_emits_warning_and_exits,
audit_deprecated_finalize_redirects_to_merge_reports,
audit_action_flags_are_mutually_exclusive (covers all 4 action
flags vs each other),
audit_prepare_writes_unified_prompt_to_canonical_location
(R10 regression assertions ported to single-file shape, plus
asserts v0 paths under audit/charters/ are NOT created).
- UPDATED merge-into tests for v1 paths (--merge-reports instead
of --finalize, .devtrail/audits/ canonical paths).
- UPDATED R11(A) default-range tests to read from the v1 prompt
location.
Test plan:
- cargo test --test charter_audit_test → 17/17 green (10 of these
are new v1 tests; 7 are R10/R11(A)/merge-into ported to v1
paths).
- cargo test (full suite) → all suites green, no regressions in
audit_skill_test (8), audit_template_test (9), or any other
test binary.
- cargo build → 1.44s (with target preserved).
- No version bump (lands together with PRs 5-8 in the integrated
v1 release per Propuesta v0.2 §5).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced May 5, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fourth of 8 PRs implementing the integrated v1 audit-skills iteration described in `Propuesta/devtrail-audit-cli-flow.md` v0.2. This is the largest refactor of the rollout — switches `devtrail charter audit` from the v0 three-step subcommand to the v1 unified flow + introduces canonical paths under `.devtrail/audits/` + deprecates the legacy templates (already replaced by the unified one in PR #105).
Subcommand changes
Canonical path migration
Resolver simplification
Templates deleted (PR #105 shipped the unified replacement)
Only `audit-prompt.md` remains.
Tests
10 new v1 tests + 7 v0-tests-ported-to-v1 = 17 total in `charter_audit_test`. Highlights:
Test plan
Phase v1 progress
🤖 Generated with Claude Code