contract-driven-delivery 1.10.0 → 1.12.0

package/assets/CLAUDE.template.md

@@ -23,4 +23,38 @@ This repository follows the Contract-Driven Delivery workflow.
 - `specs/changes/<id>/` records why decisions were made (passive archive — read only when investigating history).
 - To start any non-trivial change, use `/cdd-new <description>` in Claude Code.
 
+## CDD Kit Commands
+
+| command | when to use |
+|---|---|
+| `/cdd-new <description>` | start a new tracked change (scaffolds all artifacts, runs full agent flow) |
+| `/cdd-resume <id>` | continue an in-progress change after a session break |
+| `/cdd-close <id>` | close a completed change: promote learnings, archive |
+| `cdd-kit list` | show all active changes and their status |
+| `cdd-kit gate <id>` | verify a change is gate-ready (run before PR) |
+| `cdd-kit gate <id> --strict` | full gate with pending-task enforcement (pre-commit default) |
+| `cdd-kit archive <id>` | physically move a completed change to `specs/archive/<year>/` |
+| `cdd-kit abandon <id> --reason <text>` | mark a change as abandoned; preserves directory for git history |
+| `cdd-kit migrate <id> \| --all` | upgrade pre-v1.11 change directories to new format (frontmatter + tier format) |
+| `cdd-kit validate` | run all contract validators |
+| `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

@@ -30,6 +30,12 @@ Before editing production code, read the change artifacts, API/env/data/business
 - Read-after-write consistency — a write followed by an immediate read on a replica may return stale data.
 - Pagination — always sort by a stable column + tie-breaker (id), never offset-paginate over mutable data.
 
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
+- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
 ## Handoff
 
 Report changed files, contract updates, tests added, commands run, known risks, and next reviewer.
@@ -49,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>
@@ -70,3 +78,10 @@ with this exact structure (lines starting with `- ` are required):
 - 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>/`
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
+Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.

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,47 @@ 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:
+- AC-2:
+- AC-3:
+
+## Tasks Not Applicable
+(List task IDs from tasks.md that are NOT applicable to this change, using the format `2.2, 2.3, 4.2`. Main Claude will mark these as [-] in tasks.md.)
+- not-applicable:
+
 ## Clarifications or Assumptions
 ...
 ```
@@ -99,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>
@@ -110,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

@@ -56,6 +56,12 @@ CI/CD is mandatory. Every change must have a `ci-gates.md` plan, even if the pla
 mergeable / blocked / informational-risk
 ```
 
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
+- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
@@ -66,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>
@@ -87,3 +95,10 @@ with this exact structure (lines starting with `- ` are required):
 - 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>/`
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
+Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.

package/assets/agents/contract-reviewer.md

@@ -55,6 +55,12 @@ Record dependency or migration impacts in `contracts.md` only as contract-level
 approved / changes-required
 ```
 
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
+- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
 ## Machine-Verifiable Evidence
 
 After completing your task, include an **## Agent Log** section at the end of your response with this exact structure (lines starting with `- ` are required). The calling skill will write this block to `specs/changes/<change-id>/agent-log/contract-reviewer.md`.
@@ -65,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>
@@ -86,3 +94,10 @@ After completing your task, include an **## Agent Log** section at the end of yo
 - 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>/`
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
+Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.

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

@@ -33,6 +33,12 @@ Your tests must prove that real user journeys and realistic failure modes behave
 
 Record test files, scenarios, fixtures/mocks, commands, screenshots/videos, and mutation checks.
 
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
+- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
@@ -43,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>
@@ -64,3 +72,10 @@ with this exact structure (lines starting with `- ` are required):
 - 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>/`
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
+Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.

package/assets/agents/frontend-engineer.md

@@ -28,6 +28,12 @@ Before editing, read the change artifacts, API contract, CSS/UI contract, compon
 - Bundle size — dynamic import heavy routes; avoid full lodash / moment imports.
 - Note: avoid double-submit / rapid-action implementation bugs — but do not author monkey tests here; that is `monkey-test-engineer`'s scope.
 
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
+- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
 ## Handoff
 
 Report changed screens, component states covered, screenshots/videos if generated, tests added, commands run, and remaining UI risks.
@@ -47,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>
@@ -68,3 +76,10 @@ with this exact structure (lines starting with `- ` are required):
 - 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>/`
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
+Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.

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

@@ -36,6 +36,12 @@ Use fuzz payloads, Playwright action sequences, property-based tests, and target
 - Adversarial corpora — common boundaries (empty, max-int, NaN, Unicode RTL, Zero-Width Joiner, surrogate pairs, BOM); SQL/JS injection strings.
 - Determinism — every monkey test must seed its randomness; record the seed on failure for replay.
 
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
+- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
@@ -46,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>
@@ -66,3 +74,10 @@ with this exact structure (lines starting with `- ` are required):
 - 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>/`
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
+Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.

package/assets/agents/qa-reviewer.md

@@ -67,6 +67,12 @@ Invoke `spec-drift-auditor` at the following points (do not wait for issues to s
 approved / blocked / approved-with-risk
 ```
 
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
+- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
 ## Machine-Verifiable Evidence
 
 After completing your task, include an **## Agent Log** section at the end of your response with this exact structure (lines starting with `- ` are required). The calling skill will write this block to `specs/changes/<change-id>/agent-log/qa-reviewer.md`.
@@ -77,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>
@@ -99,3 +107,10 @@ After completing your task, include an **## Agent Log** section at the end of yo
 - 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>/`
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
+Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.

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

@@ -85,6 +85,12 @@ Your output goes into `specs/changes/<id>/design.md`. It must capture architectu
 Reference file paths instead of duplicating implementation content.
 Target: `design.md` ≤ 150 lines.
 
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
+- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
@@ -95,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>
@@ -116,3 +124,10 @@ with this exact structure (lines starting with `- ` are required):
 - 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>/`
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
+Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.

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

@@ -60,6 +60,12 @@ Use realistic load profiles rather than arbitrary request loops.
 ...
 ```
 
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
+- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
@@ -70,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>
@@ -91,3 +99,10 @@ with this exact structure (lines starting with `- ` are required):
 - 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>/`
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
+Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.

package/assets/agents/test-strategist.md

@@ -64,6 +64,12 @@ Your output goes into `specs/changes/<id>/test-plan.md`. It must answer WHAT to
 Implementation detail belongs in the test files, not in test-plan.md.
 Target: `test-plan.md` ≤ 100 lines.
 
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
+- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
@@ -74,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>
@@ -95,3 +103,10 @@ with this exact structure (lines starting with `- ` are required):
 - 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>/`
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
+Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.

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>

package/assets/cdd/context-policy.json

@@ -0,0 +1,25 @@
+{
+  "forbiddenPaths": [
+    ".claude/worktrees/**",
+    ".git/**",
+    "node_modules/**",
+    "dist/**",
+    "build/**",
+    "assets/**",
+    "specs/archive/**",
+    "specs/changes/*"
+  ],
+  "contextExpansion": {
+    "mode": "auto-safe",
+    "autoApprovePatterns": [
+      "src/**",
+      "tests/**",
+      "contracts/**",
+      "specs/changes/<current-change-id>/**"
+    ]
+  },
+  "audit": {
+    "requireFilesRead": true,
+    "unknownFilesRead": "warn-for-legacy-fail-for-new"
+  }
+}

package/assets/cdd/model-policy.json

@@ -0,0 +1,5 @@
+{
+  "provider": "claude",
+  "generated_at": null,
+  "roles": {}
+}

package/assets/contracts/api/api-contract.md

@@ -1,5 +1,8 @@
 ---
 contract: api
+summary: API behavior, compatibility rules, and endpoint contract requirements.
+owner: application-team
+surface: api
 schema-version: 0.1.0
 last-changed: 2026-04-27
 breaking-change-policy: deprecate-2-minors

package/assets/contracts/api/api-inventory.md

@@ -1,3 +1,10 @@
+---
+contract: api-inventory
+summary: Endpoint inventory categories and ownership map for non-standard API surfaces.
+owner: application-team
+surface: api
+---
+
 # API Inventory
 
 | method | path | category | owner | contract test | notes |

package/assets/contracts/api/error-format.md

@@ -1,3 +1,10 @@
+---
+contract: api-error-format
+summary: Standard error payload shape, safety rules, and reusable error code table.
+owner: application-team
+surface: api
+---
+
 # API Error Format
 
 ## Standard Error Shape

package/assets/contracts/business/business-rules.md

@@ -1,5 +1,8 @@
 ---
 contract: business
+summary: Business decision tables, rule inventory, and change policy for behavior updates.
+owner: application-team
+surface: domain-behavior
 schema-version: 0.1.0
 last-changed: 2026-04-27
 breaking-change-policy: deprecate-2-minors

package/assets/contracts/ci/ci-gate-contract.md

@@ -1,5 +1,8 @@
 ---
 contract: ci
+summary: CI gate inventory, artifact retention, and rollback requirements.
+owner: platform-team
+surface: delivery-pipeline
 schema-version: 0.1.0
 last-changed: 2026-04-27
 breaking-change-policy: deprecate-2-minors

package/assets/contracts/css/css-contract.md

@@ -1,5 +1,8 @@
 ---
 contract: css
+summary: UI token policy, component styling rules, and visual review constraints.
+owner: application-team
+surface: ui
 schema-version: 0.1.0
 last-changed: 2026-04-27
 breaking-change-policy: deprecate-2-minors

package/assets/contracts/css/design-tokens.md

@@ -1,3 +1,10 @@
+---
+contract: design-tokens
+summary: Canonical design token inventory for colors, spacing, typography, and layering.
+owner: design-system
+surface: ui
+---
+
 # Design Tokens
 
 ## Colors