contract-driven-delivery 1.11.0 → 1.12.0

package/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+## [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,9 +1,11 @@
 # 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.
 
 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.
 
+**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.
+
 ---
 
 ## Install
@@ -212,22 +214,60 @@ 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 without writing files.
+
+```bash
+cdd-kit doctor
+cdd-kit doctor --strict
+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.
+
+---
+
+### `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>`
@@ -240,10 +280,12 @@ cdd-kit gate add-jwt-auth --strict
 ```
 
 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
@@ -251,6 +293,7 @@ Checks:
 `--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 legacy changes missing `context-manifest.md` or `files-read` audit data as errors
 
 Pre-commit hook uses `--strict` by default (installed via `cdd-kit install-hooks`).
 
@@ -315,18 +358,76 @@ 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
+```
+
+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 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 +455,11 @@ 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
 ```
 
+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 +500,77 @@ 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
+```
+
+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 +601,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,21 @@ 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.
+- 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 `..`.

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

@@ -55,6 +55,8 @@ with this exact structure (lines starting with `- ` are required):
 - change-id: <id>
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
 - status: complete | needs-review | blocked
+- files-read:
+  - <repo-relative path read through tools>
 - artifacts:
   - <evidence-type>: <concrete pointer>
   - <evidence-type>: <concrete pointer>

package/assets/agents/change-classifier.md

@@ -7,7 +7,19 @@ model: claude-opus-4-7
 
 You are the change classifier for Contract-Driven Delivery.
 
-Your job is to stop premature implementation. Read the user request and nearby project context, then produce a classification report.
+Your job is to stop premature implementation. Read the user request and deterministic project context, then produce a classification report and context-manifest draft.
+
+## Context boundaries
+
+During initial classification, read only:
+- `specs/changes/<change-id>/change-request.md`
+- `specs/changes/<change-id>/context-manifest.md`
+- `specs/context/project-map.md`
+- `specs/context/contracts-index.md`
+
+Do not read `contracts/`, `src/`, `tests/`, or use broad search during initial classification unless the manifest already authorizes it. If the indexes are insufficient, add a Context Expansion Request to the manifest draft instead of reading outside this packet.
+
+Use `project-map.md` to identify candidate source/test paths and `contracts-index.md` to identify candidate contract paths. Do not invent paths that are absent from the project map or contracts index.
 
 ## Tier mapping
 
@@ -85,6 +97,37 @@ Note: `archive.md` is created during change close-out, not at classification tim
 ## Required Agents
 ...
 
+## Context Manifest Draft
+
+### Affected Surfaces
+- <surface or module>
+
+### Allowed Paths
+- specs/changes/<change-id>/
+- specs/context/project-map.md
+- specs/context/contracts-index.md
+- <candidate repo-relative path from project-map or contracts-index>
+
+### Required Contracts
+- <contract path from contracts-index, or none>
+
+### Required Tests
+- <test path or test directory from project-map, or none>
+
+### Agent Work Packets
+
+#### <agent-name>
+- allowed:
+  - specs/changes/<change-id>/
+  - <repo-relative path>
+
+### Context Expansion Requests
+- request-id: CER-001
+  requested_paths:
+    - <repo-relative path>
+  reason: <why the index is insufficient>
+  status: pending
+
 ## Inferred Acceptance Criteria
 (List 3-8 testable acceptance criteria derived from the change request. Format: `AC-N: <criterion>`. These will be used by test-strategist to populate the Acceptance Criteria → Test Mapping table.)
 - AC-1:
@@ -109,6 +152,8 @@ After completing your task, include an **## Agent Log** section at the end of yo
 - change-id: <id>
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
 - status: complete | needs-review | blocked
+- files-read:
+  - <repo-relative path read through tools>
 - artifacts:
   - <evidence-type>: <concrete pointer>
   - <evidence-type>: <concrete pointer>
@@ -120,6 +165,7 @@ After completing your task, include an **## Agent Log** section at the end of yo
 - `risk`: low|medium|high|critical
 - `required-artifacts`: list
 - `required-reviewers`: list of agent names
+- `context-manifest-draft`: allowed paths and agent work packets based only on `project-map.md` and `contracts-index.md`
 
 ### Rules
 - NEVER omit this log file. `cdd-kit gate` rejects changes whose agent-log

package/assets/agents/ci-cd-gatekeeper.md

@@ -72,6 +72,8 @@ with this exact structure (lines starting with `- ` are required):
 - change-id: <id>
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
 - status: complete | needs-review | blocked
+- files-read:
+  - <repo-relative path read through tools>
 - artifacts:
   - <evidence-type>: <concrete pointer>
   - <evidence-type>: <concrete pointer>

package/assets/agents/contract-reviewer.md

@@ -71,6 +71,8 @@ After completing your task, include an **## Agent Log** section at the end of yo
 - change-id: <id>
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
 - status: complete | needs-review | blocked
+- files-read:
+  - <repo-relative path read through tools>
 - artifacts:
   - <evidence-type>: <concrete pointer>
   - <evidence-type>: <concrete pointer>

package/assets/agents/dependency-security-reviewer.md

@@ -72,6 +72,8 @@ After completing your task, include an **## Agent Log** section at the end of yo
 - change-id: <id>
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
 - status: complete | needs-review | blocked
+- files-read:
+  - <repo-relative path read through tools>
 - artifacts:
   - <evidence-type>: <concrete pointer>
   - <evidence-type>: <concrete pointer>

package/assets/agents/e2e-resilience-engineer.md

@@ -49,6 +49,8 @@ with this exact structure (lines starting with `- ` are required):
 - change-id: <id>
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
 - status: complete | needs-review | blocked
+- files-read:
+  - <repo-relative path read through tools>
 - artifacts:
   - <evidence-type>: <concrete pointer>
   - <evidence-type>: <concrete pointer>

package/assets/agents/frontend-engineer.md

@@ -53,6 +53,8 @@ with this exact structure (lines starting with `- ` are required):
 - change-id: <id>
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
 - status: complete | needs-review | blocked
+- files-read:
+  - <repo-relative path read through tools>
 - artifacts:
   - <evidence-type>: <concrete pointer>
   - <evidence-type>: <concrete pointer>

package/assets/agents/monkey-test-engineer.md

@@ -52,6 +52,8 @@ with this exact structure (lines starting with `- ` are required):
 - change-id: <id>
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
 - status: complete | needs-review | blocked
+- files-read:
+  - <repo-relative path read through tools>
 - artifacts:
   - <evidence-type>: <concrete pointer>
   - <evidence-type>: <concrete pointer>

package/assets/agents/qa-reviewer.md

@@ -83,6 +83,8 @@ After completing your task, include an **## Agent Log** section at the end of yo
 - change-id: <id>
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
 - status: complete | needs-review | blocked
+- files-read:
+  - <repo-relative path read through tools>
 - artifacts:
   - <evidence-type>: <concrete pointer>
   - <evidence-type>: <concrete pointer>

package/assets/agents/repo-context-scanner.md

@@ -92,6 +92,8 @@ After completing your task, include an **## Agent Log** section at the end of yo
 - change-id: <id>
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
 - status: complete | needs-review | blocked
+- files-read:
+  - <repo-relative path read through tools>
 - artifacts:
   - <evidence-type>: <concrete pointer>
   - <evidence-type>: <concrete pointer>

package/assets/agents/spec-architect.md

@@ -101,6 +101,8 @@ with this exact structure (lines starting with `- ` are required):
 - change-id: <id>
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
 - status: complete | needs-review | blocked
+- files-read:
+  - <repo-relative path read through tools>
 - artifacts:
   - <evidence-type>: <concrete pointer>
   - <evidence-type>: <concrete pointer>

package/assets/agents/spec-drift-auditor.md

@@ -61,6 +61,8 @@ Use this exact structure (lines starting with `- ` are required):
 - audit-id: <YYYY-MM-DD>-drift
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
 - status: complete | needs-review | blocked
+- files-read:
+  - <repo-relative path read through tools>
 - artifacts:
   - <evidence-type>: <concrete pointer>
   - <evidence-type>: <concrete pointer>

package/assets/agents/stress-soak-engineer.md

@@ -76,6 +76,8 @@ with this exact structure (lines starting with `- ` are required):
 - change-id: <id>
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
 - status: complete | needs-review | blocked
+- files-read:
+  - <repo-relative path read through tools>
 - artifacts:
   - <evidence-type>: <concrete pointer>
   - <evidence-type>: <concrete pointer>

package/assets/agents/test-strategist.md

@@ -80,6 +80,8 @@ with this exact structure (lines starting with `- ` are required):
 - change-id: <id>
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
 - status: complete | needs-review | blocked
+- files-read:
+  - <repo-relative path read through tools>
 - artifacts:
   - <evidence-type>: <concrete pointer>
   - <evidence-type>: <concrete pointer>

package/assets/agents/ui-ux-reviewer.md

@@ -59,6 +59,8 @@ After completing your task, include an **## Agent Log** section at the end of yo
 - change-id: <id>
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
 - status: complete | needs-review | blocked
+- files-read:
+  - <repo-relative path read through tools>
 - artifacts:
   - <evidence-type>: <concrete pointer>
   - <evidence-type>: <concrete pointer>

package/assets/agents/visual-reviewer.md

@@ -61,6 +61,8 @@ After completing your task, include an **## Agent Log** section at the end of yo
 - change-id: <id>
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
 - status: complete | needs-review | blocked
+- files-read:
+  - <repo-relative path read through tools>
 - artifacts:
   - <evidence-type>: <concrete pointer>
   - <evidence-type>: <concrete pointer>