contract-driven-delivery 1.11.0 → 1.16.0

package/CHANGELOG.md

@@ -0,0 +1,205 @@
+# Changelog
+
+## [1.16.0] - 2026-04-30
+
+### Visual narration: per-agent stage badges
+
+- `/cdd-new` skill now instructs main Claude to prefix every agent
+  invocation announcement with a colored emoji badge tagging the role and
+  stage. Non-engineer users can scan the chat stream and see "we're at
+  review now, not implementation" without reading prompts.
+- Six color buckets:
+  - 🟣 decision (classifier, architect — opus-class)
+  - 🔵 implementation (backend, frontend, ci-cd, sonnet-class)
+  - 🟡 test planning (test-strategist)
+  - 🟠 heavy testing (e2e, monkey, stress — Tier 0–1 only; orange = scope warning)
+  - 🟢 review (read-only verdicts)
+  - ⚫ audits & scans (background, read-only)
+- `/cdd-resume` references the same badge table so resumed flows look
+  consistent.
+
+### Notes
+
+This is the only PR in the v1.13 follow-up series that changes the visible
+chat narration. Prompt-only; no code or test changes.
+
+## [1.15.0] - 2026-04-30
+
+### Workflow safety net (defaults that protect non-engineers)
+
+- `cdd-kit new` auto-runs `context-scan` when `specs/context/*.md` indexes are
+  missing or stale (B5 hash-based check). Avoids classifier wasting a round
+  on outdated paths. New `--skip-scan` for advanced users.
+- `cdd-kit gate` now lints `tasks.md` frontmatter:
+  - Requires `change-id` and `status`.
+  - Validates `status` against known set (`in-progress`, `completed`,
+    `gate-blocked`, `abandoned`, `needs-review`, `complete`, `done`).
+  - Warns on unknown keys with did-you-mean suggestions (e.g. `Tier:` →
+    `did you mean tier?`). Catches the typo class that previously caused
+    silent enforcement skips.
+- `cdd-kit gate` now detects `depends-on` cycles via DFS and reports the
+  full cycle path (e.g. `feat-a → feat-b → feat-c → feat-a`).
+- `cdd-kit doctor --fix`: auto-resolves the safe subset of warnings
+  - regenerates stale or missing `specs/context/*.md` indexes
+  - populates empty `model-policy.json` roles with defaults
+  - leaves invasive fixes (`.cdd/*` missing → suggests `cdd-kit upgrade`)
+    for the user to confirm
+- `cdd-kit gate`: artifact-pointer existence check now runs **by default**
+  (previously `--strict`-only). Use `--lax` to skip for legacy repos with
+  unfixed agent logs.
+
+### Tests
+
+- 11 new tests across `gate.test.ts` (frontmatter lint, DAG cycle, default
+  pointer check), `new.test.ts` (auto-scan), `doctor.test.ts` (--fix).
+- Updated `gate.test.ts` test 13b — its premise inverted by PR-3 #6.
+- Updated `writeValidChangeArtifacts` helper to include required frontmatter.
+
+## [1.14.0] - 2026-04-30
+
+### Agent efficiency for non-engineer users
+
+- `/cdd-new` Step 0: request-quality pre-lint. Refuses to run when the user's
+  request is missing affected-surface, desired-behavior, or success-criterion.
+  Avoids one full classifier round-trip on ambiguous requests.
+- `change-classifier`: atomic-split detection. Mega-requests crossing 2+
+  change-types or 3+ surfaces now return an `## Atomic Split Proposal` table
+  with suggested `cdd-kit new --depends-on` commands instead of a single
+  Tier 0/1 monolith. Estimated 40-60% token saving on multi-feature requests.
+- `references/agent-log-protocol.md`: every agent must self-validate its log
+  block before sending its response. Prevents the round-trip where gate
+  catches a malformed log and forces a full agent re-run.
+- `/cdd-new` Step 4 fix-back: structured error-to-agent routing table. Each
+  gate error class now has a defined re-invocation owner and a templated
+  prompt prefix that includes the verbatim gate error. No more "blind retry".
+
+### Notes
+
+This release is prompt-only (no code changes in `src/`). Improvements are
+qualitative for the AI agent flow, not exposed as new CLI flags.
+
+## [1.13.0] - 2026-04-29
+
+### Token-budget reductions
+- Shared `references/agent-log-protocol.md` — extracted the duplicated agent-log
+  format block out of all 16 agent prompts. Total agent-prompt size dropped
+  from 1675 → 1344 lines (≈20% smaller). One source of truth, no drift.
+- `/cdd-new` skill no longer inlines the 5 change-template bodies; `cdd-kit
+  new` writes them from disk. Skill went from 483 → ~340 lines (≈30%).
+- Tier 5 fast-path for docs/prompts/config-only changes — classifier now
+  short-circuits the full agent flow when no source/tests/contracts are
+  touched; bounds doc-only token cost to 2 read-only reviews.
+- `context-manifest.md` template no longer duplicates the forbidden-paths list
+  that `.cdd/context-policy.json` already carries.
+- `cdd-kit context-scan` now caps per-directory entries to 50 and supports
+  `--surface <path>` to scope the project map to a sub-tree.
+
+### Stability hardening
+- Tier source moved to `tasks.md` frontmatter `tier: <0-5>`. The legacy
+  `## Tier\n- N` and `**Tier:** Tier N` formats remain as fallback-only;
+  bold-only legacy format produces a migration warning instead of silently
+  skipping tier-specific agent enforcement.
+- Section-7 archive exemption is no longer hard-coded `7\.[12]`; reads from
+  `tasks.md` frontmatter `archive-tasks: ["7.1", "7.2"]` (default preserved).
+- `cdd-kit migrate` is now atomic: per-session backup at
+  `.cdd/migrate-backup/<timestamp>/`, two-phase tmp-write + rename, restore
+  hint on failure. New `--no-backup` opt-out.
+- `cdd-kit migrate` now backfills `tier:` and `archive-tasks:` into legacy
+  `tasks.md` frontmatter automatically.
+- `cdd-kit doctor` freshness check is now content-hash based, not mtime.
+  `git clone` no longer triggers spurious staleness warnings.
+- `cdd-kit context approve|reject --all-pending` resolves every pending
+  Context Expansion Request in one command.
+- `cdd-kit gate` now reconciles agent self-reported `files-read:` against the
+  runtime hook log at `.cdd/runtime/<change-id>-files-read.jsonl`. Undeclared
+  reads warn (or fail under `--strict`).
+- `hooks/post-tool-use-files-read.sh` — Claude Code PostToolUse hook scaffold
+  that records actual Read/Grep/Glob targets for the gate to verify.
+- `cdd-kit gate` now invokes `validate` in-process instead of via
+  `spawnSync(process.execPath, [process.argv[1], ...])`. No more `argv[1]`
+  indirection or extra Node startup.
+- `.cdd/model-policy.json` ships with real role-to-model defaults (no longer
+  empty `{}`). `cdd-kit doctor` warns when an installed agent's `model:`
+  frontmatter drifts from policy. `init`/`upgrade` preserve any custom
+  `roles` overrides instead of clobbering them.
+
+### Skill updates
+- `/cdd-new` now lints classifier output before writing files (`## Tier`,
+  `## Required Agents`, `## Inferred Acceptance Criteria` must be filled).
+- `/cdd-new` writes the classifier's tier into `tasks.md` frontmatter as the
+  authoritative source.
+
+### Tests
+- 19 new tests covering B1–B7 + A5 + B3. 39 gate tests, 15 migrate tests, 9
+  context tests, 7 doctor tests all pass.
+
+## [1.12.0] - 2026-04-29
+
+### Added
+- `cdd-kit doctor --json` for CI and machine-readable repository health checks.
+- `cdd-kit upgrade --migrate-changes [--enable-context-governance]` to combine repo-level upgrade work with legacy change migration.
+- `cdd-kit context request`, `cdd-kit context reject`, and `cdd-kit context list [--json]` for a fuller context expansion workflow.
+
+### Changed
+- Default contract templates now include deterministic `summary`, `owner`, and `surface` metadata so fresh repos do not start with avoidable `contracts-index` warnings.
+- `cdd-kit context-scan` now excludes `contracts/CHANGELOG.md` from the contracts index.
+- Shared provider inference is now reused by `update`, `doctor`, and `upgrade`.
+- Migration messaging now refers to the current cdd-kit format instead of pinning docs to one release number.
+
+### Docs
+- README now includes production rollout guidance for old repos, with separate migration paths for completed specs and in-progress specs.
+- Release checklist now covers `doctor --json`, `upgrade --migrate-changes`, and post-upgrade context governance decisions.
+
+## [1.11.0] - 2026-04-28
+
+### Added
+- Context Governance v1 for new changes: `context-manifest.md`, `files-read` audit expectations, default forbidden paths, and legacy-vs-new gate behavior.
+- Provider adapter scaffold for Claude Code and Codex: `init --provider claude|codex|both`, provider-aware `update`, and `.cdd/model-policy.json`.
+- `cdd-kit context-scan`: deterministic `specs/context/project-map.md` and `specs/context/contracts-index.md` indexes for lower-token classification.
+- `cdd-kit doctor`: repo health checks for missing config, provider guidance, stale context indexes, and contract summary gaps.
+- `cdd-kit upgrade`: dry-run-first repo-level upgrade command that adds missing cdd-kit files without overwriting existing project guidance or contracts.
+- `cdd-kit context approve <change-id> <request-id>`: approves pending expansion requests and records approved paths in the manifest.
+- Atomic change dependencies with `cdd-kit new --depends-on` and gate blocking until upstream changes complete or archive.
+- `/cdd-new`, `/cdd-resume`, and `/cdd-close` prompt hardening for manifest-scoped reads, hot/warm/cold data handling, and context index usage.
+
+### Changed
+- `cdd-kit migrate` can add legacy or context-governed manifests and opt old changes into `context-governance: v1`.
+- README now describes provider-neutral usage, context governance, upgrade flow, and context expansion approval.
+
+### Notes
+- Context Governance audits and discourages unauthorized reads. It is not a runtime sandbox and still depends on agent-log evidence plus gate review.
+
+## [1.10.0] - 2026-04-27
+
+### Added
+- `cdd-kit gate --strict`: pending `[ ]` tasks are errors in strict mode; pre-commit hook now uses `--strict` by default. Section-7 archive tasks (7.1, 7.2) are exempt.
+- `cdd-kit gate`: artifact pointer validation in strict mode. Each path listed under `- artifacts:` in agent logs is verified to exist on disk.
+- `cdd-kit gate`: tier-based agent-log requirements. Tier 0-1 changes must have `e2e-resilience-engineer`, `monkey-test-engineer`, and `stress-soak-engineer` logs; Tier 0-3 must have `contract-reviewer` and `qa-reviewer`.
+- `cdd-kit gate`: differentiated minimum char counts per artifact (change-classification and test-plan >= 200, ci-gates >= 150, others >= 100).
+- `cdd-kit gate`: scoped validate call to `--contracts --env --ci --versions`.
+- `cdd-kit abandon <change-id> --reason <text>`: marks a change as abandoned in `tasks.md` and records it in `specs/archive/INDEX.md`.
+- `cdd-kit archive <change-id>`: moves a completed change from `specs/changes/` to `specs/archive/<year>/`.
+- `/cdd-close` skill synthesizes `archive.md` from `agent-log/` and `qa-report.md` before archiving, then invokes `contract-reviewer` for durable promotion diffs.
+- `/cdd-resume` resumes an in-progress change across sessions by reading `tasks.md` and `agent-log/` to determine the next pending agent.
+- `change-classifier` now outputs `## Inferred Acceptance Criteria` and `## Tasks Not Applicable`.
+- All agents require `CURRENT_CHANGE_ID: <id>` in every prompt.
+- `cdd-new` injects `CURRENT_CHANGE_ID` into every agent call, auto-marks N/A tasks with `[-]`, and passes acceptance criteria to `test-strategist`.
+- `cdd-kit migrate <change-id> | --all [--dry-run]`: upgrades existing change directories from pre-v1.11 format. Adds YAML frontmatter plus `[x]/[-]/[ ]` legend to `tasks.md`; converts old `**Tier:** Tier N` to `## Tier\n- N`.
+
+### Fixed
+- Tier detection regex tightened to avoid matching unfilled classifier templates.
+- Agent read-scope placeholder `<current-change-id>` replaced with runtime `CURRENT_CHANGE_ID` injection.
+- `archive.md` removed from `/cdd-new` opt-in surface because it is synthesized at close time.
+
+## [1.0.1] - 2026-04-20
+
+### Fixed
+- CLI binary renamed from `cdd` to `cdd-kit` for npm uniqueness.
+- Corrected bin path format for npm 11.x compatibility.
+
+## [1.0.0] - 2026-04-20
+
+### Added
+- Initial release of the contract-driven-delivery CLI (`cdd-kit`).
+- Commands: `init`, `new`, `gate`, `validate`, `detect-stack`.
+- Tier-based change classification, contract scaffolding, and agent-log validation.

package/README.md

@@ -1,8 +1,10 @@
 # Contract-Driven Delivery Kit
 
-**cdd-kit** is a Claude Code development kit that turns AI agents into a disciplined engineering team: contracts-first, test-first, spec-first. Every change goes through classification, contract review, TDD, implementation, and gate verification — automatically orchestrated by Claude Code skills.
+**cdd-kit** is a contract-driven delivery kit for AI coding agents. It started with Claude Code skills and now keeps the core workflow provider-neutral: contracts-first, test-first, spec-first. Every change goes through classification, contract review, TDD, implementation, and gate verification, with deterministic context indexes and manifest-backed read-scope auditing to keep long agent runs reviewable.
 
-Designed for solo developers and small teams building brownfield production systems (dashboards, APIs, workflow tools, data apps) who want AI to do all the implementation while they stay in the spec-author and reviewer seat.
+Designed for solo developers and small teams building brownfield production systems (dashboards, APIs, workflow tools, data apps), especially when non-engineers or product owners want AI to do the implementation while they stay in the spec-author and reviewer seat.
+
+**Context Governance v1** adds a manifest-driven audit layer for AI agents. New changes include `context-manifest.md`, `agent-log` entries are expected to report `files-read`, and `cdd-kit gate` audits those reads against allowed and forbidden paths. This is governance and review support, not a sandbox.
 
 ---
 
@@ -88,11 +90,14 @@ or
 
 **What happens:**
 1. Claude generates a `change-id` (e.g. `add-jwt-auth`) and scaffolds `specs/changes/add-jwt-auth/`
-2. The `change-classifier` agent (Opus) reads the request, classifies risk and tier, decides which agents are needed
-3. Agents run in order: contracts → test plan → spec/architecture review (if needed) → backend engineer → frontend engineer → CI/CD gates → QA
-4. Each agent produces machine-verifiable evidence (agent-log files)
-5. `cdd-kit gate <change-id>` runs automatically to confirm all artifacts are complete
-6. Claude reports a summary and the suggested git commit
+2. If the request is ambiguous, Claude asks back for affected surface, desired behavior, and success criterion before spending a classifier round-trip
+3. The `change-classifier` agent (Opus) reads the request, classifies risk and tier, decides which agents are needed
+4. If the request is too broad, the classifier can return an atomic split proposal instead of forcing one Tier 0/1 monolith
+5. For Tier 0-1 work, Claude's narration uses stage badges so users can tell whether the flow is deciding, implementing, testing, or reviewing
+6. Agents run in order: contracts → test plan → spec/architecture review (if needed) → backend engineer → frontend engineer → CI/CD gates → QA
+7. Each agent produces machine-verifiable evidence (agent-log files)
+8. `cdd-kit gate <change-id>` runs automatically to confirm all artifacts are complete
+9. Claude reports a summary and the suggested git commit
 
 **You stay in control by:**
 - Reviewing the `change-classification.md` before implementation starts
@@ -212,22 +217,61 @@ Installs agents and skill into `~/.claude` and scaffolds project files.
 cdd-kit init                  # global + local (recommended)
 cdd-kit init --global-only    # only install into ~/.claude
 cdd-kit init --local-only     # only scaffold project files
+cdd-kit init --provider codex # scaffold Codex-oriented project guidance
+cdd-kit init --provider both  # scaffold Claude Code + Codex guidance
 cdd-kit init --force          # overwrite existing project files
 ```
 
-Creates: `contracts/`, `specs/templates/`, `CLAUDE.md`, `AGENTS.md`, `hooks/`
+Creates: `contracts/`, `specs/templates/`, provider guidance files (`CLAUDE.md`, `AGENTS.md`, and/or `CODEX.md`), `hooks/`
 
 ---
 
 ### `cdd-kit update`
 
-Updates agents and skill in `~/.claude` to the latest installed version. Does not touch `contracts/` or `CLAUDE.md`.
+Updates provider assets to the latest installed version. By default, `update` reads `.cdd/model-policy.json` and updates only the matching provider adapter. It does not overwrite project guidance files such as `CLAUDE.md`, `AGENTS.md`, or `CODEX.md`.
 
 ```bash
 cdd-kit update
 cdd-kit update --yes          # apply without confirmation
+cdd-kit update --provider codex
+cdd-kit update --provider both
 ```
 
+Codex currently has no global assets to update, so Codex-only projects report that they are already up to date. Run `cdd-kit init --local-only --provider codex` if a project is missing `CODEX.md`.
+
+---
+
+### `cdd-kit doctor`
+
+Inspects repo-level cdd-kit health. Default mode is read-only; `--fix` applies only the safe auto-remediations.
+
+```bash
+cdd-kit doctor
+cdd-kit doctor --strict
+cdd-kit doctor --fix
+cdd-kit doctor --json
+cdd-kit doctor --provider codex
+```
+
+Checks for missing `.cdd/` policy files, provider guidance (`CLAUDE.md`, `AGENTS.md`, `CODEX.md`), context indexes, stale `specs/context/*` outputs, and contract summary metadata gaps. `--strict` treats warnings as errors. `--json` emits a machine-readable report for CI or wrapper scripts. `--fix` currently auto-runs `context-scan` for stale or missing indexes and backfills empty `.cdd/model-policy.json` role bindings, but deliberately does not run invasive repo upgrades for you.
+
+---
+
+### `cdd-kit upgrade`
+
+Adds missing repo-level cdd-kit files after upgrading the npm package. It preserves existing contracts and guidance files; default mode is a dry run.
+
+```bash
+cdd-kit upgrade
+cdd-kit upgrade --yes
+cdd-kit upgrade --yes --migrate-changes
+cdd-kit upgrade --yes --migrate-changes --enable-context-governance
+cdd-kit upgrade --provider codex --yes
+cdd-kit upgrade --provider both --yes
+```
+
+Use this for old repos that already have `contracts/` or `specs/` but are missing new assets such as `.cdd/context-policy.json`, `.cdd/model-policy.json`, `CODEX.md`, or newer templates. Add `--migrate-changes` if you also want to upgrade existing `specs/changes/<change-id>/` directories in the same run.
+
 ---
 
 ### `cdd-kit gate <change-id>`
@@ -237,20 +281,26 @@ The single quality gate for a change. Blocks merge if anything is missing or inc
 ```bash
 cdd-kit gate add-jwt-auth
 cdd-kit gate add-jwt-auth --strict
+cdd-kit gate add-jwt-auth --lax
 ```
 
 Checks:
-- All 5 required artifacts exist (`change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.md`)
+- All required artifacts exist (`change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.md`; new context-governed changes also require `context-manifest.md`)
 - Each artifact has sufficient content (not a stub): change-classification ≥ 200 chars, test-plan ≥ 200, ci-gates ≥ 150, others ≥ 100
 - `change-classification.md` contains a tier or risk marker
 - `agent-log/*.md` files all have `status: complete` (not blocked)
+- For context-governed changes, `agent-log/*.md` files include a structured `- files-read:` list and those repo-relative paths are audited against `context-manifest.md` and `.cdd/context-policy.json`
+- Atomic `depends-on` upstream changes are completed or archived before dependent work gates
 - Tier 0–1 changes have `e2e-resilience-engineer`, `monkey-test-engineer`, and `stress-soak-engineer` logs
 - Tier 0–3 changes have `contract-reviewer` and `qa-reviewer` logs
 - All contract validators pass
 
 `--strict` additionally:
 - Treats any pending `[ ]` tasks (except section 7 archive items) as errors
-- Validates that every file path listed in `agent-log` artifact pointers actually exists on disk
+- Treats runtime-vs-declared `files-read` drift as errors
+- Treats legacy changes missing `context-manifest.md` or `files-read` audit data as errors
+
+Default mode also validates that artifact file pointers listed in `agent-log` evidence exist on disk. Use `--lax` only when cleaning up legacy repos with stale historical logs.
 
 Pre-commit hook uses `--strict` by default (installed via `cdd-kit install-hooks`).
 
@@ -315,18 +365,78 @@ Upgrades pre-v1.11.0 change directories to the current format.
 cdd-kit migrate add-jwt-auth        # migrate one change
 cdd-kit migrate --all               # migrate all changes in specs/changes/
 cdd-kit migrate --all --dry-run     # preview without writing
+cdd-kit migrate --all --enable-context-governance
 ```
 
 What it upgrades:
 - `tasks.md`: adds YAML frontmatter (`change-id`, `status: in-progress`) and `[x]/[-]/[ ]` legend if missing
 - `change-classification.md`: detects old `**Tier:** Tier N` format and appends the new `## Tier\n- N` section so tier-based gate checks activate
+- `context-manifest.md`: adds a legacy manifest scaffold by default so old changes can continue with warning-only context audit behavior
+- `--enable-context-governance`: explicitly adds `context-governance: v1` and a context-governed manifest scaffold, making missing manifest or malformed `files-read` data hard gate failures
+
+`agent-log/*.md` must use this `files-read` format for context-governed changes:
+
+```md
+- files-read:
+  - contracts/api/api-contract.md
+  - src/server/routes/users.ts
+```
+
+Paths must be repo-relative. Absolute paths and `..` parent traversal are rejected.
 
 Run this after upgrading from v1.10 or earlier if you have mid-flight changes.
 
 ```bash
 cdd-kit migrate --all
 git add specs/changes/
-git commit -m "chore: migrate changes to v1.11.0 format"
+git commit -m "chore: migrate changes to current cdd-kit format"
+```
+
+---
+
+### `cdd-kit context request <change-id> <request-id>`
+
+Records a pending Context Expansion Request in `context-manifest.md`.
+
+```bash
+cdd-kit context request add-jwt-auth CER-001 --path src/server/users.ts tests/users.test.ts --reason "paired implementation and regression coverage"
+```
+
+Use this when an agent needs more context than its current work packet allows.
+
+---
+
+### `cdd-kit context approve <change-id> <request-id>`
+
+Approves a pending Context Expansion Request in `context-manifest.md` and adds its `requested_paths` to `## Approved Expansions`.
+
+```bash
+cdd-kit context approve add-jwt-auth CER-001
+cdd-kit context approve add-jwt-auth --all-pending   # bulk approve every pending request
+```
+
+This keeps expansion history explicit while avoiding manual manifest editing. Agents still have to report `files-read` in `agent-log/*.md`; `cdd-kit gate` audits those paths against the manifest.
+
+---
+
+### `cdd-kit context reject <change-id> <request-id>`
+
+Rejects a pending Context Expansion Request and records `status: rejected` in the manifest.
+
+```bash
+cdd-kit context reject add-jwt-auth CER-001
+cdd-kit context reject add-jwt-auth --all-pending   # bulk reject every pending request
+```
+
+---
+
+### `cdd-kit context list <change-id>`
+
+Lists all Context Expansion Requests for a change.
+
+```bash
+cdd-kit context list add-jwt-auth
+cdd-kit context list add-jwt-auth --json
 ```
 
 ---
@@ -354,8 +464,14 @@ Scaffolds an empty change directory. Normally you use `/cdd-new` (the Claude Cod
 cdd-kit new add-user-auth
 cdd-kit new add-user-auth --all     # include optional templates too
 cdd-kit new add-user-auth --force   # overwrite existing directory
+cdd-kit new add-user-api --depends-on add-user-db
+cdd-kit new add-user-auth --skip-scan
 ```
 
+By default, `cdd-kit new` auto-runs `cdd-kit context-scan` when `specs/context/` indexes are missing or stale. Use `--skip-scan` only if you intentionally want a bare scaffold without refreshing classifier indexes first.
+
+For larger requests, split the work into atomic changes on the same feature branch and use `--depends-on` to record upstream order. `cdd-kit gate` blocks a dependent change until each upstream change is either archived or has `status: completed` in its `tasks.md` frontmatter.
+
 ---
 
 ### `cdd-kit install-hooks`
@@ -396,25 +512,78 @@ cdd-kit detect-stack
 
 ---
 
-## Upgrading from v1.10 or earlier
+### `cdd-kit context-scan`
+
+Builds deterministic, low-token context indexes for classifiers and orchestrators.
+
+```bash
+cdd-kit context-scan
+cdd-kit context-scan --surface src/server   # scope project-map to a sub-tree (large monorepos)
+```
+
+Outputs:
+- `specs/context/project-map.md`: ASCII directory tree with schema metadata, visible file/dir counts, and excluded paths from `.cdd/context-policy.json`
+- `specs/context/contracts-index.md`: contract inventory table plus deterministic details from YAML frontmatter or `<!-- cdd: ... -->` metadata
+
+Recommended contract metadata:
+
+```yaml
+---
+contract: api
+summary: User API endpoint rules and compatibility policy.
+owner: backend-team
+surface: user-management
+---
+```
+
+The classifier should read these two files before proposing `context-manifest.md` allowed paths.
+
+---
+
+## Migrating an Older Production Repo
 
 ```bash
 npm update -g contract-driven-delivery
-cdd-kit update
+cdd-kit upgrade --yes
+cdd-kit context-scan
+cdd-kit doctor --strict
+```
+
+### Old completed specs
+
+If a change is already finished, merged, or only kept for audit/history:
 
-# If you have mid-flight changes:
+```bash
 cdd-kit migrate --all
 git add specs/changes/
-git commit -m "chore: migrate changes to v1.11.0 format"
+git commit -m "chore: migrate changes to current cdd-kit format"
+```
+
+This gives those legacy specs the new `tasks.md` frontmatter, tier markers, and a warning-mode `context-manifest.md` without forcing strict context governance on closed work.
+
+### Old in-progress specs
+
+If a change is still being actively developed:
+
+```bash
+cdd-kit upgrade --yes --migrate-changes
+cdd-kit context-scan
+cdd-kit doctor --strict
 ```
 
-**What changed in v1.11.0:**
-- `gate --strict` and pre-commit enforcement
-- Tier-based agent-log requirements (Tier 0–1 must have E2E/monkey/stress logs)
-- `cdd-kit abandon`, `cdd-kit archive`, `cdd-kit list`, `cdd-kit migrate` commands
-- `/cdd-resume` and `/cdd-close` Claude Code skills
-- `change-classifier` outputs Acceptance Criteria + Tasks Not Applicable
-- All agents require `CURRENT_CHANGE_ID` injection (handled automatically by skills)
+Then choose one path per active change:
+
+- Conservative path: keep the migrated legacy manifest, resume work, and let `gate` warn on missing `files-read` data while the team transitions.
+- Strict path: run `cdd-kit migrate <change-id> --enable-context-governance`, review `context-manifest.md`, narrow `Allowed Paths`, and require agents to report `- files-read:` before continuing implementation.
+
+### Recommended rollout for production repos already burned by token overuse
+
+1. Run `cdd-kit upgrade --yes` once per repo after updating the npm package.
+2. Run `cdd-kit context-scan` so classifiers can read `specs/context/project-map.md` and `specs/context/contracts-index.md` instead of broad repo searches.
+3. Run `cdd-kit doctor --strict` in CI.
+4. Migrate old completed specs with plain `cdd-kit migrate`.
+5. Migrate active specs with `cdd-kit migrate --enable-context-governance` only after reviewing the generated manifest.
+6. Teach agents to use `cdd-kit context request/approve/reject/list` instead of silently widening context.
 
 ---
 
@@ -445,7 +614,8 @@ your-repo/
 │   └── templates/
 ├── tests/
 ├── CLAUDE.md                        ← Claude's project guide (edit this)
-└── AGENTS.md                        ← agent roster (auto-managed)
+├── AGENTS.md                        ← agent roster (auto-managed)
+└── CODEX.md                         ← Codex project guide when initialized for Codex
 ```
 
 ---

package/assets/CLAUDE.template.md

@@ -40,3 +40,13 @@ This repository follows the Contract-Driven Delivery workflow.
 | `cdd-kit detect-stack` | detect the project tech stack |
 
 Run `cdd-kit detect-stack` to verify the detected tech stack.
+
+## Context Governance
+
+For context-governed changes, read `specs/changes/<change-id>/context-manifest.md` before using file-reading or broad search tools.
+
+- Read only paths allowed by the manifest or approved expansions.
+- If more context is needed, stop and write a Context Expansion Request in the manifest (`cdd-kit context request`).
+- The full agent-log format (including `files-read:` schema) is defined in
+  `~/.claude/skills/contract-driven-delivery/references/agent-log-protocol.md`.
+  Read that once; do not paraphrase it elsewhere.

package/assets/CODEX.template.md

@@ -0,0 +1,39 @@
+# CODEX.md
+
+This project uses Contract-Driven Delivery (CDD).
+
+## Workflow
+
+- Treat `contracts/` as the current source of truth.
+- Treat `specs/changes/<change-id>/` as active work context.
+- Treat `specs/archive/` as historical context only; do not use it for current planning unless explicitly asked.
+- Start non-trivial work by creating a change with `cdd-kit new <change-id>`.
+- Run `cdd-kit context-scan` before classification when project context may be stale.
+- Run `cdd-kit gate <change-id>` before proposing a commit or PR.
+
+## Context Governance
+
+Read `specs/changes/<change-id>/context-manifest.md` before using file-reading or search tools.
+
+- Read only paths allowed by the manifest or approved expansions.
+- Do not use broad repository search unless the manifest authorizes it.
+- If more context is needed, stop and write a Context Expansion Request in the manifest.
+- Record every file read through tools in the relevant `agent-log/*.md` under `- files-read:`.
+
+Required `agent-log/*.md` format:
+
+```md
+- files-read:
+  - contracts/api/api-contract.md
+  - src/server/routes/users.ts
+```
+
+Every entry must be a repo-relative path. Do not omit files, use absolute paths, or use `..`.
+
+## Hot And Cold Data
+
+- Hot: `contracts/`, source files, tests, CI config.
+- Warm: current `specs/changes/<change-id>/`.
+- Cold: `specs/archive/`.
+
+Cold historical data is evidence, not current requirements.

package/assets/agents/backend-engineer.md

@@ -47,19 +47,10 @@ In your agent log, reference file paths and function names — do not paste code
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
-with this exact structure (lines starting with `- ` are required):
-
-```
-# Backend Engineer Log
-- change-id: <id>
-- timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
-- status: complete | needs-review | blocked
-- artifacts:
-  - <evidence-type>: <concrete pointer>
-  - <evidence-type>: <concrete pointer>
-- next-action: <one line, or "none">
-```
+After completing your task, write or append to
+`specs/changes/<change-id>/agent-log/<your-agent-name>.md`. Required fields,
+field rules, and gate-enforcement behavior are defined once in
+`references/agent-log-protocol.md` — do not duplicate them in this prompt.
 
 ### Required artifacts for this agent
 - `files-changed`: list of `path/to/file.ts:line-range`
@@ -67,16 +58,6 @@ with this exact structure (lines starting with `- ` are required):
 - `test-output`: last 10 lines of `npm test` or equivalent stdout
 - `contracts-touched`: list of contract file paths or "none"
 
-### Rules
-- NEVER omit this log file. `cdd-kit gate` rejects changes whose agent-log
-  is missing the `status:` line or has an invalid status.
-- If you cannot complete the task, set `status: blocked` and write a
-  concrete `next-action` (NOT "investigate further" — write the actual
-  next step a human can act on).
-- Evidence must be concrete: file:line, command name + last-10-line stdout,
-  contract path + section, test name, etc. NEVER write "verified" or "OK"
-  without a pointer.
-
 ## Read scope
 
 - Allowed: `contracts/`, `tests/`, `src/`, `specs/changes/<current-change-id>/`