From 4037c6382926c017bcd5b728deb95b795b67fa50 Mon Sep 17 00:00:00 2001 From: Mumit Khan Date: Fri, 1 May 2026 16:53:35 -0700 Subject: [PATCH] docs: refresh all documentation for v1.2.0 elevation work MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md: updated Status section from stale v1.0.0 claim to v1.0/1.1/1.2 framing; added `npm run budget` and `npm run visualize` to CLI list - AGENTS.md: added budget (init/update/check) and visualize command shims - CHANGELOG.md: fixed broken cross-refs from `docs/releases/` (non-existent) to the real `docs/release-notes/` directory - .codex/rules/compaction.md: corrected Stage 5→Stage 6 for review files (Stage 5 is pre-review; Stage 6 is peer review in codex numbering) - .codex/skills/pipeline/SKILL.md: added budget check and visualize commands to the Finish section - docs/parity/claude-dev-team-parity.md: updated date, added budget/visualize/ checkpoint entries to "Codex Improvements Beyond Claude", updated stale v1.0 Blockers section to reflect current parity status - docs/release-notes/v1.1.0.md: new file covering deepening commit - docs/release-notes/v1.2.0.md: new file covering elevation work (unreleased) - .gitignore: added pipeline/diagram.md (runtime visualize artifact) VERSION kept at 1.0.0: v1.2.0 work is unreleased on this PR branch; VERSION and framework.version should only be bumped in a dedicated release commit. Co-Authored-By: Claude Sonnet 4.6 --- .codex/rules/compaction.md | 4 +- .codex/skills/pipeline/SKILL.md | 13 +++++++ .gitignore | 3 ++ AGENTS.md | 4 ++ CHANGELOG.md | 6 +-- README.md | 20 ++++++++-- docs/parity/claude-dev-team-parity.md | 21 +++++++++-- docs/release-notes/v1.1.0.md | 35 +++++++++++++++++ docs/release-notes/v1.2.0.md | 54 +++++++++++++++++++++++++++ 9 files changed, 147 insertions(+), 13 deletions(-) create mode 100644 docs/release-notes/v1.1.0.md create mode 100644 docs/release-notes/v1.2.0.md diff --git a/.codex/rules/compaction.md b/.codex/rules/compaction.md index c6a9aa2..3c58db6 100644 --- a/.codex/rules/compaction.md +++ b/.codex/rules/compaction.md @@ -10,8 +10,8 @@ pipeline safely. 3. Open `ESCALATE` gates and their `decision_needed` text. 4. Open `QUESTION:` and `CONCERN:` entries in `pipeline/context.md`. 5. Stage 4 build areas that are complete. -6. Stage 5 review files that have been written. -7. Stage 5 review round count per area, including changes-requested cycles. +6. Stage 6 review files that have been written. +7. Stage 6 review round count per area, including changes-requested cycles. 8. Retry count and owning role for any stage currently retrying. 9. Stage 9a agents that have contributed. 10. Whether Stage 9b synthesis completed and which lessons were promoted or diff --git a/.codex/skills/pipeline/SKILL.md b/.codex/skills/pipeline/SKILL.md index bfbf7f0..ba18d8f 100644 --- a/.codex/skills/pipeline/SKILL.md +++ b/.codex/skills/pipeline/SKILL.md @@ -132,6 +132,19 @@ If the retrospective contains durable learning, write lines beginning with npm run lessons -- promote ``` +To visualize the final pipeline state: + +```bash +npm run visualize +``` + +If budget tracking is enabled (`budget.enabled: true` in `.codex/config.yml`), +check running totals at any time with: + +```bash +npm run budget -- check +``` + ## Stage Gates High-value stages have schema-backed required fields: diff --git a/.gitignore b/.gitignore index fdbc2ba..53ae97a 100644 --- a/.gitignore +++ b/.gitignore @@ -22,3 +22,6 @@ pipeline/adr/ # Generated local packaging notes docs/pr/ + +# Runtime visualize artifact (generated by npm run visualize) +pipeline/diagram.md diff --git a/AGENTS.md b/AGENTS.md index 9156375..22b8051 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -69,6 +69,10 @@ instead of creating package metadata just for the framework. | `/audit-quick [scope]` | `npm run audit:quick -- ""` | | `/health-check` | `npm run health-check` | | Claude parity checklist | `npm run parity:check` | +| Init budget tracking | `npm run budget -- init` | +| Update budget after stage | `npm run budget -- update ` | +| Check budget totals | `npm run budget -- check` | +| Visualize pipeline state | `npm run visualize` | ## Local vs Cloud diff --git a/CHANGELOG.md b/CHANGELOG.md index a722ab7..adf354d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ All notable changes to the `codex-dev-team` framework are recorded here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project follows [Semantic Versioning](https://semver.org/). -Per-release detail lives in [`docs/releases/`](docs/releases/). This file +Per-release detail lives in [`docs/release-notes/`](docs/release-notes/). This file is the index and the rolling `[Unreleased]` pointer — it stays thin so `git log` diffs between tags are readable. @@ -122,8 +122,8 @@ Codex-native conventions. ## How to add a new release entry -1. Create `docs/releases/vX.Y.Z.md` following the shape in - [`docs/releases/README.md`](docs/releases/README.md). +1. Create `docs/release-notes/vX.Y.Z.md` following the shape of + [`docs/release-notes/v1.0.0.md`](docs/release-notes/v1.0.0.md). 2. Add a row to the release map table above (reverse chronological). 3. Move the relevant `[Unreleased]` entries into the release file, leaving `[Unreleased]` empty or listing only changes not yet released. diff --git a/README.md b/README.md index be5edfb..abc8224 100644 --- a/README.md +++ b/README.md @@ -73,10 +73,18 @@ examples/ ## Status -`v1.0.0` is at feature parity with the local `claude-dev-team` framework and -adds Codex-native CLI automation, JSON status/roadmap outputs, deployment -adapters, strict parity checks, and dogfood install coverage. It remains -local-only by design until you decide to publish a remote. +`v1.0.0` shipped at feature parity with the local `claude-dev-team` framework +and added Codex-native CLI automation, JSON status/roadmap outputs, deployment +adapters, strict parity checks, and dogfood install coverage. + +`v1.1.0` deepened that parity: role prompts fleshed out, audit-phases reference +added, budget/checkpoint config blocks added to `.codex/config.yml`, approval +locking hardened, and parity-check coverage expanded. + +`v1.2.0` (unreleased, on branch `codex/elevate-with-claude-depth`) adds prose +depth to all rule files, `scripts/budget.js` and `scripts/visualize.js`, async +checkpoint auto-pass logic, `EXAMPLE.md`, `CHANGELOG.md`, and `CONTRIBUTING.md`. +The framework remains local-only by design until you decide to publish a remote. ## CLI @@ -132,6 +140,10 @@ npm run review:derive npm run security:check -- src/backend/auth/session.js npm run runbook:check npm run autofold +npm run budget -- init +npm run budget -- update +npm run budget -- check +npm run visualize npm run lessons -- show npm run lessons -- promote ``` diff --git a/docs/parity/claude-dev-team-parity.md b/docs/parity/claude-dev-team-parity.md index eee354b..8253831 100644 --- a/docs/parity/claude-dev-team-parity.md +++ b/docs/parity/claude-dev-team-parity.md @@ -1,9 +1,9 @@ # Claude Dev Team Parity Checklist -Last updated: 2026-04-30 +Last updated: 2026-05-01 This checklist tracks whether `codex-dev-team` is on par with the local -`claude-dev-team` framework. Release notes remain deferred until v1.0. +`claude-dev-team` framework. ## Summary @@ -77,6 +77,13 @@ This checklist tracks whether `codex-dev-team` is on par with the local - Deployment adapters are documented and configured locally. - Track-aware `next`, `prompt`, and `autofold` helpers reduce manual orchestration. - Gate schemas and contract tests guard framework drift. +- `scripts/budget.js` (`npm run budget`) — opt-in token and wall-clock tracking + per pipeline run; escalates or warns when configured maxima are exceeded. +- `scripts/visualize.js` (`npm run visualize`) — Mermaid stateDiagram-v2 + generator colors each stage by gate status; output is `pipeline/diagram.md`. +- Async checkpoint auto-pass logic — `checkpoints.a/b/c` in `.codex/config.yml` + accept `no_warnings` or `all_criteria_passed` conditions so unattended runs can + advance without a human `proceed` when the precondition holds. ## Stage Numbering Divergence @@ -108,5 +115,11 @@ eliminates one extra JSON gate file, not the security check itself. ## v1.0 Blockers -- None. `npm run parity:check` now fails if any command row, required rule, - required skill, partial area, or v1.0 gap is present. +- None. `npm run parity:check` fails if any command row, required rule, + required skill, partial area, or known gap is present. + +## Parity Status + +`v1.0.0` was the initial parity release. `v1.1.0` deepened structural coverage. +`v1.2.0` (unreleased) adds shared runtime features (budget, visualize, +checkpoint auto-pass) that go beyond what `claude-dev-team` offers. diff --git a/docs/release-notes/v1.1.0.md b/docs/release-notes/v1.1.0.md new file mode 100644 index 0000000..a3906d7 --- /dev/null +++ b/docs/release-notes/v1.1.0.md @@ -0,0 +1,35 @@ +# Release v1.1.0 + +Date: 2026-05-01 + +Deepening commit `f852b91 feat: deepen claude-dev-team parity`. + +## Verification + +- npm run lint +- npm test +- npm run doctor +- npm run parity:check + +## What Changed + +### Fixed / Expanded + +- **Role definitions** fleshed out to 1,287 lines with full working rules and + output formats for every role (`pm`, `principal`, `backend`, `frontend`, + `platform`, `qa`, `reviewer`, `security`). +- **Audit phases reference** added at `.codex/references/audit-phases.md` (264 + lines) covering quick, full, and health-check audit modes. +- **Budget gate** — `.codex/config.yml` now has `budget.enabled`, `tokens_max`, + `wall_clock_max_minutes`, and `on_exceed` fields. +- **Async checkpoints** — `.codex/config.yml` now has `checkpoints.a/b/c` + with `auto_pass_when` conditions. +- **Stoplist enforcement** — `.codex/rules/pipeline.md` Stage 0 documents the + six stoplist triggers that force the full track. +- **Approval locking** — `scripts/approval-derivation.js` uses atomic file + writes to prevent race conditions when the hook fires concurrently. +- **Parity check** — `scripts/parity-check.js` performs deep structural checks. + +## Commits + +- f852b91 feat: deepen claude-dev-team parity diff --git a/docs/release-notes/v1.2.0.md b/docs/release-notes/v1.2.0.md new file mode 100644 index 0000000..1906525 --- /dev/null +++ b/docs/release-notes/v1.2.0.md @@ -0,0 +1,54 @@ +# Release v1.2.0 + +Date: Unreleased (branch `codex/elevate-with-claude-depth`) + +## Verification + +- npm run lint +- npm test +- npm run doctor +- npm run parity:check + +## What Changed + +### Added + +- `.codex/rules/pipeline.md` expanded to ~400 lines with full prose for review + shape (scoped vs matrix), review file format, READ-ONLY Reviewer Rule, gate + merge strategy, review round limit, Stage Duration Expectations, and Parallel + Execution Model. +- `.codex/rules/gates.md` expanded to ~200 lines with Stage-Specific Extra + Fields including concrete JSON examples for every codex stage, scoped vs + matrix review shape JSON, Stage 08 auto-fold semantics, retry protocol, and + ESCALATE shape examples. +- `.codex/rules/coding-principles.md` expanded to ~110 lines with numbered + principles, "what TO do / what NOT to do" code examples, and a Precedence + section. +- `.codex/rules/execution-profiles.md` expanded to ~80 lines covering the three + execution profiles (`local`, `app_worktree`, `cloud`) in detail, including a + "Parallelism in Stage 4" subsection. +- `EXAMPLE.md` at repo root — end-to-end pipeline walkthrough for "Add password + reset via email", covering Stages 1–9 with real artifact excerpts. +- `CHANGELOG.md` at repo root — version history following Keep a Changelog. +- `CONTRIBUTING.md` at repo root — local dev setup, test/lint/parity commands, + PR conventions, and stage numbering note. +- `scripts/budget.js` — budget tracking: `init`, `update`, `check` subcommands. + Writes `pipeline/budget.md`, appends per-stage rows, and checks totals against + config maxima. No-op when `budget.enabled: false`. +- `scripts/visualize.js` — Mermaid stateDiagram-v2 generator. Reads active + track stages and gate files, colors by status, writes `pipeline/diagram.md`. +- `scripts/codex-team.js`: `budget` and `visualize` subcommands wired in. +- Checkpoint auto-pass logic in `scripts/codex-team.js`: + `applyCheckpointAutoPass()` called after gate writes; supports `no_warnings` + and `all_criteria_passed` conditions; suppressed when stoplist triggers appear + in `pipeline/context.md`. +- `tests/budget.test.js`, `tests/checkpoints.test.js`, `tests/visualize.test.js`. +- `npm run budget` and `npm run visualize` scripts in `package.json`. +- `pipeline/diagram.md` added to `.gitignore` (runtime visualize artifact). +- `docs/release-notes/v1.1.0.md` and `docs/release-notes/v1.2.0.md` created. + +## Commits + +- 40c29d1 fix(gate-validator): deterministic tiebreaker for latest-gate sort +- 016d989 feat: elevate codex with claude depth and shared runtime features +- f852b91 feat: deepen claude-dev-team parity