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
Eighth and final PR of Phase 2. Lifts the version footers and example
outputs across the canonical surface, adds CLI-REFERENCE entries for
the new commands shipped in PRs 1-7, and writes the consolidated
CHANGELOG entry that lists all 7 PRs as one release.
Version bumps:
- cli/Cargo.toml: 3.6.1 → 3.7.0 (Cargo.lock auto-updated)
- dist/dist-manifest.yml: 4.5.1 → 4.6.0
- 13 governance footers (5 EN + 4 ES + 4 zh-CN): v4.5.1 → v4.6.0
- README.md, docs/i18n/es/README.md, docs/i18n/zh-CN/README.md
versioning tables: fw-4.5.1 → fw-4.6.0, cli-3.6.1 → cli-3.7.0
- CLI-REFERENCE.md (3 langs) example outputs: same bump
Documentation:
- README.md (3 langs): commands tables list charter close/drift,
approve, validate --check-pending-reviews.
- docs/adopters/CLI-REFERENCE.md (EN canonical):
* `devtrail init [--hooks]` — flag documented.
* `devtrail validate` — --check-pending-reviews + --max-pending-days
flags documented; warn-only behavior called out.
* `devtrail charter close` — full subsection: two modes, pre-fills,
target time, schema validation.
* `devtrail charter drift` — full subsection: AILOG-aware
suppression, exit codes, platform note about bash dependency.
* `devtrail approve` — new top-level section: behavior, flags,
multi-reviewer convention, pointer to DOCUMENTATION-POLICY §3.5.
- ES + zh-CN CLI-REFERENCE keeps the version-footer bumps; the
command-section translations are deferred to fw-4.6.x (CHANGELOG
notes the deferral explicitly).
CHANGELOG:
- New `## Framework 4.6.0 / CLI 3.7.0` consolidated section.
- Lists all 7 Phase 2 PRs by feature group (Added Framework, Changed
Framework, Added CLI, Changed CLI, Notes, Test plan summary).
- Closes issue #67 reference (resolved by PR 4).
- Compatibility statement: no breaking changes; new commands and
fields are additive.
382/382 tests pass.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The first feature-bearing release since the repositioning (fw-4.5.x). Phase 2 of `Propuesta/devtrail-cli-roadmap.md` lands as 7 bisect-safe PRs (#73–#79), grouped here for reviewers. The release closes the empirical loop the Sentinel experiment opened: telemetry at Charter close, drift detection at Charter close, and a canonical approval signal for `review_required: true` documents (resolving issue #67).
13
+
14
+
**Compatibility.** No breaking changes. Existing Charters, AILOGs, AIDECs, and templates remain valid. New CLI commands and framework artifacts are additive; new template fields ship as commented YAML so existing documents continue to validate. Adopters pick up the changes via `devtrail update-framework` + `devtrail update-cli`.
15
+
16
+
### Added (Framework)
17
+
18
+
-**`dist/.devtrail/schemas/charter-telemetry.schema.v0.json`** — JSON Schema Draft 2020-12 for the post-execution telemetry recorded at Charter close. Derived from `Propuesta/devtrail-charter-telemetry.md` v0.3 with the 4 fields refined by Sentinel: `external_audit` as array (dual-audit calibration), `outcome.scope_change_notes` with F1...FN encoding, `agent_quality.r_n_plus_one_emergent_count`, `qualitative.format_iteration`. Marked **experimental v0** — same N=1-domain caveat as `charter.schema.v0.json`. (PR #73)
19
+
-**`dist/.devtrail/templates/charter-telemetry-template.yaml`** — commented YAML skeleton mirroring the schema. Used by `devtrail charter close --from-template` as the starting point for manual edits. (PR #73)
20
+
-**`dist/.devtrail/scripts/check-charter-drift.sh`** — bash script (~165 lines) ported from Sentinel `scripts/check-plan-drift.sh`. Detects declared-but-not-modified files and undocumented scope expansion. Validated empirically with zero false positives across PLAN-05 retrospective + PLAN-06 prospective in Sentinel. Path surface adapted (`docs/plans/` → `docs/charters/`) and section heading detection extended to EN/ES/zh-CN. (PR #73)
21
+
-**`dist/.devtrail/hooks/pre-pr.sh`** — opt-in pre-push hook that runs `devtrail charter drift` automatically on Charters with `status: in-progress`. Per principle #6 (cognitive discipline > raw productivity), the hook is virtuous when consented to and never installed by default. Manual install: `cp .devtrail/hooks/pre-pr.sh .git/hooks/pre-push`. CLI flag: `devtrail init --hooks`. (PR #79)
22
+
-**Approval workflow canonization** (PR #76, closes issue #67): 3 optional frontmatter fields (`reviewed_by`, `reviewed_at`, `review_outcome`) added to all 11 templates that need formal approval (AIDEC, ETH, MCARD, ADR, DPIA, INC, SEC + China: PIPIA, CACFILE, TC260RA, AILABEL) across EN, ES, and zh-CN — **33 template files**. Fields ship as commented YAML so existing documents continue to validate. The presence of `review_outcome` is the canonical "human has reviewed" signal; `review_required: true` remains as historical record after approval (it's not toggled to `false`).
23
+
24
+
### Changed (Framework)
25
+
26
+
-**`dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md`** (EN + ES + zh-CN):
27
+
- §2 Optional Fields extended with `reviewed_by`, `reviewed_at`, `review_outcome`.
28
+
- New §3.5 "Recording Approval" section explaining closure semantics, body section format (compatible with existing `## Approval` tables in 7 templates), the multi-reviewer convention for v1 (chronological body blocks; structured array deferred), and the CLI tooling.
29
+
30
+
### Added (CLI)
31
+
32
+
-**`devtrail charter close <CHARTER-ID>`** (PR #74) — record post-execution telemetry and bump status to `closed`. Two modes:
33
+
-**Interactive** (default): walks the schema field by field — trigger, effort, agent quality, outcome, qualitative — rendering YAML directly so the output is stable, comment-free, and validated against the schema before disk write. Target time: 5–10 min.
34
+
-**`--from-template [--non-interactive]`**: copies the YAML skeleton next to the Charter for manual editing (CI / scripted use). Pre-fills `charter_id`, title, and `closed_at`. Idempotent.
35
+
- Telemetry storage: `.devtrail/charters/CHARTER-NN.telemetry.yaml` (lateral file, not embedded in Charter frontmatter — per roadmap §A2: frontmatter is declarative ex-ante, telemetry is voluminous ex-post).
36
+
-**`devtrail charter drift <CHARTER-ID>`** (PR #75) — wraps `check-charter-drift.sh` with **AILOG-awareness**: paths reported as "declared but not modified" are silenced when they appear in the `## Risk` / `## Riesgos` / `## 风险` section of any AILOG referenced by the Charter's `originating_ailogs`. This is mitigation R2 of the Sentinel experiment — friction was virtuous when emitting cross-agent signal, ceremony when alerting on already-documented risks. Flags: `--range REV..REV` (default `HEAD~1..HEAD`), `--no-ailog-suppress` (disable suppression), `--path DIR`. Bash delegation only; pure-Rust fallback for Windows-without-bash deferred until requested.
37
+
-**`devtrail approve <doc-id>`** (PR #77) — record a formal human approval. Writes the three approval frontmatter fields and appends the canonical `## Approval` body section in one atomic edit. Flag-driven for CI (`--outcome <approved|revisions_requested|rejected> --reviewer <id> [--at YYYY-MM-DD] [--notes "..."]`); falls back to interactive prompts on TTY when flags are absent. Resolves any DocType by canonical prefix, supports re-approval (latest-wins in frontmatter, both blocks preserved chronologically in body for the multi-reviewer convention).
38
+
-**`devtrail validate --check-pending-reviews [--max-pending-days N]`** (PR #78) — surfaces documents with `review_required: true` and no `review_outcome` older than the threshold. **Warn-only** (never errors): per principle #6, useful for CI dashboards of the approval backlog without blocking unrelated PRs. Default threshold: 14 days.
39
+
-**`devtrail init --hooks`** (PR #79) — copies `.devtrail/hooks/pre-pr.sh` to `.git/hooks/pre-push` after init. Refuses to overwrite existing hooks; skips silently if not a git repo.
40
+
41
+
### Changed (CLI)
42
+
43
+
- New shared module `cli/src/prompts.rs` — interactive helpers (string, u32, bool, enum, comma-separated array, multiline) with `require_interactive()` guard, used by `charter close` and `approve`.
44
+
- New `cli/src/telemetry_schema.rs` — JSON Schema validator for telemetry YAML, mirroring `charter_schema.rs`.
45
+
- New `cli/src/charter_schema.rs::yaml_to_json_value` — exposed as `pub` (renamed from private `yaml_to_json`) so `telemetry_schema` and other future schema validators can reuse the conversion without duplication.
46
+
-`cli/src/document.rs::Frontmatter` — added `reviewed_by`, `reviewed_at`, `review_outcome` as `Option<String>` so `validate --check-pending-reviews` can read them.
47
+
48
+
### Notes
49
+
50
+
-**No schema changes to `charter.schema.v0.json`** — Phase 2 is additive in the Charter ecosystem, not breaking.
51
+
-**Empirical validation gate** — Sentinel's PLAN-05 + PLAN-06 fixtures (zero false positives) are the contractual reference for `charter drift`. The integration tests in PR #75 reproduce the equivalent shape against a real git repo. The Sentinel-side telemetry artifacts (5 PLAN-NN.telemetry.yaml files) are the cross-validation set for the schema crystallized here.
52
+
-**i18n parity** — DOCUMENTATION-POLICY §3.5 ships in all three languages this release; CLI-REFERENCE EN gets the new command sections in this release, ES + zh-CN command-section translations are deferred to fw-4.6.x (the EN canonical surface advances first, ES + zh-CN translations of the command tables stay at the current command list with a brief note).
53
+
54
+
### Test plan summary
55
+
56
+
**382/382 tests pass** across 15 test groups: 4 hook-install unit tests, 6 approve integration tests, 4 drift integration tests, 5 charter-close integration tests, 4 pending-review integration tests, plus the existing 359 covering the rest of the CLI. Manual smoke of the interactive `charter close` flow remains an open item before tag.
57
+
58
+
---
59
+
10
60
## Framework 4.5.1 — i18n catch-up + ADOPTION-GUIDE reframe (ES + zh-CN follow up to fw-4.5.0)
11
61
12
62
Completes the repositioning shipped in `fw-4.5.0` for the Spanish and Simplified Chinese surfaces, and reframes `docs/adopters/ADOPTION-GUIDE.md` (English) — which had been overlooked in `fw-4.5.0` and was still leading with the *"ISO 42001-aligned AI governance platform"* framing. After this release, the canonical engineering-discipline-first positioning is consistent across all three languages.
Built-in commands that turn the discipline into actionable feedback:
133
133
134
-
-**`devtrail charter <new|list|status>`** — Bounded units of work declared ex-ante, audited ex-post (the unit of agent execution)
135
-
-**`devtrail validate`** — 25+ validation rules for document correctness (12 China-specific are scope-aware); `--include-charters` extends to `docs/charters/`
134
+
-**`devtrail charter <new|list|status|close|drift>`** — Bounded units of work declared ex-ante, audited ex-post (the unit of agent execution). `close` records post-execution telemetry; `drift` detects file-vs-commit drift with AILOG-aware suppression.
135
+
-**`devtrail approve <doc-id>`** — Record a formal human approval (writes `reviewed_by` / `reviewed_at` / `review_outcome` and the `## Approval` body section in one edit; closes the gap canonized in DOCUMENTATION-POLICY §3.5)
136
+
-**`devtrail validate`** — 25+ validation rules for document correctness (12 China-specific are scope-aware); `--include-charters` extends to `docs/charters/`; `--check-pending-reviews` lists approval backlog (warn-only)
| `devtrail validate [path]` | Validate documents for compliance and correctness (use `--include-charters` to also check `docs/charters/`) |
278
-
| `devtrail charter <subcommand>` | Manage Charters: `new`, `list`, `status` (bounded units of work declared ex-ante, audited ex-post) |
278
+
| `devtrail validate [path]` | Validate documents for compliance and correctness (use `--include-charters` for Charters, `--check-pending-reviews` for approval backlog) |
279
+
| `devtrail charter <subcommand>` | Manage Charters: `new`, `list`, `status`, `close` (record telemetry), `drift` (file-vs-commit drift with AILOG-awareness) |
280
+
| `devtrail approve <doc-id>` | Record a formal human approval on a `review_required: true` document (frontmatter + canonical body section) |
279
281
| `devtrail compliance [path]` | Check regulatory compliance (EU AI Act, ISO 42001, NIST) |
280
282
| `devtrail metrics [path]` | Show governance metrics and documentation statistics |
0 commit comments