contract-driven-delivery 2.0.16 → 2.0.17

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [2.0.17] - 2026-05-07
+
+Focused index-assisted development release. Agents now get a smaller, more
+precise pre-read path through the code-map, while `cdd-kit gate` returns to
+delivery-quality validation instead of post-run harness paperwork.
+
+### Added
+
+- **`cdd-kit index query <term>`**: searches `.cdd/code-map.yml` for matching
+  files, imports, symbols, and line ranges, auto-refreshing a missing or stale
+  map before returning candidates.
+- **`cdd-kit index impact <path-or-symbol>`**: reports indexed local imports and
+  dependent files so agents can inspect the smallest useful modification scope
+  before editing.
+
+### Changed
+
+- **Gate is now delivery-quality only**: `cdd-kit gate` validates required
+  artifacts, tasks, tier consistency, dependencies, and contract validators,
+  without requiring agent logs, files-read lists, or code-map freshness as
+  merge blockers.
+- **Agent prompts prefer index-first targeting**: implementation agents are
+  instructed to use `index query` before broad source reads and `index impact`
+  before editing chosen source files.
+- **Agent logs are optional handoff notes**: prompt templates and protocols no
+  longer require agents to create logs or reconstruct every file they read just
+  to satisfy a gate.
+
 ## [2.0.16] - 2026-05-06
 
 New-change scaffold hardening so freshly opened proposals use the installed

package/README.md

@@ -1,10 +1,10 @@
-# Contract-Driven Delivery Kit
+# Contract-Driven Delivery Kit
 
-**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.
+**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 to keep agent work targeted.
 
 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.
+**Context Governance v1** adds a manifest-driven planning layer for AI agents. New changes include `context-manifest.md`; agents should use `cdd-kit index query` and `cdd-kit index impact` before broad source reads. `cdd-kit gate` focuses on delivery quality, not post-run read paperwork.
 
 ---
 
@@ -38,7 +38,7 @@ cdd-kit init
 
 ## How to Direct Claude Code
 
-> All workflows are started by typing a **natural language instruction** to Claude Code in your IDE or terminal. The `/cdd-*` prefixed commands are Claude Code skills — not shell commands.
+> All workflows are started by typing a **natural language instruction** to Claude Code in your IDE or terminal. The `/cdd-*` prefixed commands are Claude Code skills ??not shell commands.
 
 ### Starting a new project (first time)
 
@@ -94,8 +94,8 @@ or
 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)
+6. Agents run in order: contracts ??test plan ??spec/architecture review (if needed) ??backend engineer ??frontend engineer ??CI/CD gates ??QA
+7. Agents write implementation artifacts and optional concise handoff notes
 8. `cdd-kit gate <change-id>` runs automatically to confirm all artifacts are complete
 9. Claude reports a summary and the suggested git commit
 
@@ -108,7 +108,7 @@ Use a lightweight maintenance lane for small corrections where the intent is alr
 | Lane | Examples | Required record |
 |---|---|---|
 | maintenance / micro-change | typo fixes, comment updates, README cleanup, formatting, lint-only fixes, tiny local test repair | normal commit message and test output if applicable |
-| tracked CDD change | behavior changes, contract updates, API/data/env/security/CI changes, cross-module refactors, high-risk bug fixes | `specs/changes/<id>/`, `tasks.yml`, `context-manifest.md`, agent logs, and `cdd-kit gate` |
+| tracked CDD change | behavior changes, contract updates, API/data/env/security/CI changes, cross-module refactors, high-risk bug fixes | `specs/changes/<id>/`, `tasks.yml`, `context-manifest.md`, and `cdd-kit gate` |
 
 Do not add hard pre-commit rules that block every `src/`, `tests/`, or `contracts/` edit unless your team explicitly wants that policy. The default kit favors low-friction traceability: make risky changes reviewable, but let obvious maintenance edits stay small.
 
@@ -118,8 +118,8 @@ Machine-readable metadata such as future `change.yml` / `trace.yml` should follo
 
 CDD uses two agent classes on purpose:
 
-- `change-classifier`, `contract-reviewer`, `qa-reviewer`, `visual-reviewer`, `dependency-security-reviewer`, `ui-ux-reviewer`, `repo-context-scanner`, and `spec-drift-auditor` are read-only. They return analysis, verdicts, or an `Agent Log` YAML block; main Claude writes the corresponding files.
-- `backend-engineer`, `frontend-engineer`, `e2e-resilience-engineer`, `monkey-test-engineer`, `stress-soak-engineer`, `ci-cd-gatekeeper`, `test-strategist`, and `spec-architect` are write-capable. They write their own implementation artifacts and their own `agent-log/*.yml`.
+- `change-classifier`, `contract-reviewer`, `qa-reviewer`, `visual-reviewer`, `dependency-security-reviewer`, `ui-ux-reviewer`, `repo-context-scanner`, and `spec-drift-auditor` are read-only. They return analysis, verdicts, or optional handoff notes; main Claude writes the corresponding files.
+- `backend-engineer`, `frontend-engineer`, `e2e-resilience-engineer`, `monkey-test-engineer`, `stress-soak-engineer`, `ci-cd-gatekeeper`, `test-strategist`, and `spec-architect` are write-capable. They write their own implementation artifacts directly.
 
 This split is deliberate:
 
@@ -130,7 +130,7 @@ This split is deliberate:
 **You stay in control by:**
 - Reviewing the `change-classification.md` before implementation starts
 - Checking the `test-plan.md` to confirm the right test families are planned
-- Reading the final `agent-log/qa-reviewer.yml` for the release-readiness verdict
+- Reading the final QA summary for the release-readiness verdict
 
 ---
 
@@ -148,7 +148,7 @@ This split is deliberate:
 /cdd-new add Redis caching layer to the reporting queries
 ```
 
-The change-classifier will detect that these are architectural or contract-level changes, assign a higher risk tier (0–2), and automatically require:
+The change-classifier will detect that these are architectural or contract-level changes, assign a higher risk tier (0??), and automatically require:
 - Architecture review (`spec-architect` agent)
 - E2E, resilience, stress, and monkey tests
 - Updated contracts before any implementation begins
@@ -170,7 +170,7 @@ What changes are currently in progress? (cdd-kit list)
 ```
 
 **What happens:**
-1. Claude reads `tasks.yml` and `agent-log/` to determine what was completed
+1. Claude reads `tasks.yml` and existing change artifacts to determine what was completed
 2. Reports the current state (which agents ran, which tasks are pending)
 3. Asks if you want to continue from the next pending agent
 4. Resumes the full agent flow from where it stopped, with no duplication
@@ -189,9 +189,9 @@ After the PR is merged:
 
 **What happens:**
 1. Runs `cdd-kit gate` to confirm the change still passes
-2. Synthesizes `archive.md` — a permanent record of what changed, what tests were added, and what lessons were found
+2. Synthesizes `archive.md` ??a permanent record of what changed, what tests were added, and what lessons were found
 3. Promotes only evidence-backed durable learnings to `contracts/` or project guidance (`CLAUDE.md`/`CODEX.md`). General agents record evidence and findings only; durable learning promotion happens during `/cdd-close` Step 3.
-4. Runs `cdd-kit archive add-jwt-auth` — moves the change from `specs/changes/` to `specs/archive/2026/`
+4. Runs `cdd-kit archive add-jwt-auth` ??moves the change from `specs/changes/` to `specs/archive/2026/`
 5. Reduces the active context that future Claude sessions need to load
 
 ---
@@ -235,7 +235,7 @@ Active changes:
 
 ## CLI Reference
 
-These are shell commands — not Claude Code skills. Run them directly in the terminal, or Claude Code will run them on your behalf.
+These are shell commands ??not Claude Code skills. Run them directly in the terminal, or Claude Code will run them on your behalf.
 
 ### `cdd-kit init`
 
@@ -311,36 +311,27 @@ 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 required artifacts exist (`change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.yml`; 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/*.yml` files all have a completed status (`complete`, with `done` and `approved` accepted as compatibility aliases) and are not blocked
-- For context-governed changes, `agent-log/*.yml` 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
+- Each artifact has sufficient content and is not a stub.
+- `change-classification.md` contains a tier or risk marker.
+- Atomic `depends-on` upstream changes are completed or archived before dependent work gates.
+- All contract validators pass.
 
 `--strict` additionally:
 - Treats any task with `status: pending` (except IDs listed in `archive-tasks`) as an error
-- 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.
+- Treats legacy changes missing `context-manifest.md` as errors
 
 Pre-commit hook uses `--strict` by default (installed via `cdd-kit install-hooks`).
 
 ```
-✓  gate passed for change: add-jwt-auth
+?? gate passed for change: add-jwt-auth
 
-✗  gate failed for change: feat-001
-✗    change-classification.md: appears to be a stub (< 200 meaningful chars)
-✗    Tier 1 change requires agent-log/e2e-resilience-engineer.yml
-✗    1 task(s) still pending (mark archive items in archive-tasks frontmatter; mark N/A items as status: skipped)
+?? gate failed for change: feat-001
+??   change-classification.md: appears to be a stub (< 200 meaningful chars)
+??   1 task(s) still pending (mark archive items in archive-tasks frontmatter; mark N/A items as status: skipped)
 ```
 
 ---
@@ -368,11 +359,11 @@ Physically moves a completed change from `specs/changes/` to `specs/archive/<yea
 
 ```bash
 cdd-kit archive add-jwt-auth
-# ✓  Archived: specs/changes/add-jwt-auth → specs/archive/2026/add-jwt-auth
-# ✓  Index updated: specs/archive/INDEX.md
+# ?? Archived: specs/changes/add-jwt-auth ??specs/archive/2026/add-jwt-auth
+# ?? Index updated: specs/archive/INDEX.md
 ```
 
-Warns (but does not block) if `tasks.yml` has pending items or `status: gate-blocked`. Use after `/cdd-close` — the skill runs this automatically at the end.
+Warns (but does not block) if `tasks.yml` has pending items or `status: gate-blocked`. Use after `/cdd-close` ??the skill runs this automatically at the end.
 
 ---
 
@@ -382,7 +373,7 @@ Marks a change as abandoned. Updates `tasks.yml` status to `abandoned`, records
 
 ```bash
 cdd-kit abandon add-jwt-auth --reason "using Auth0 instead"
-# ✓  Change add-jwt-auth marked as abandoned.
+# ?? Change add-jwt-auth marked as abandoned.
 ```
 
 ---
@@ -401,10 +392,10 @@ cdd-kit migrate --all --enable-context-governance
 What it upgrades:
 - `tasks.yml`: converts legacy `tasks.md` checklist/frontmatter into structured YAML task records
 - `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
+- `context-manifest.md`: adds a legacy manifest scaffold by default so old changes can use the same pre-read planning layer
+- `--enable-context-governance`: explicitly adds `context-governance: v1` and a context-governed manifest scaffold for pre-read planning
 
-`agent-log/*.yml` must use this `files-read` format for context-governed changes:
+If you choose to emit `agent-log/*.yml`, keep `files-read` optional and concise:
 
 ```yaml
 files-read:
@@ -412,10 +403,8 @@ files-read:
   - src/server/routes/users.ts
 ```
 
-Paths must be repo-relative. Absolute paths and `..` parent traversal are rejected.
-If a logged read is legitimate but gate says it is unauthorized, add that path
-to `context-manifest.md` `## Allowed Paths` or approve a Context Expansion
-Request. Do not remove it from `files-read`; that list is the audit trail.
+Paths should be repo-relative. Do not reconstruct this list after the fact;
+use `cdd-kit context check` before invoking agents when read scope matters.
 
 Run this after upgrading from v1.10 or earlier if you have mid-flight changes.
 
@@ -449,11 +438,10 @@ cdd-kit context check add-todos-ui --path src/components/Sidebar.vue src/stores/
 cdd-kit context check add-ci-gate --path contracts/ci/ci-gate-contract.md .github/workflows/contract-driven-gates.yml
 ```
 
-The check uses the same authorization model as `cdd-kit gate`: `## Allowed
-Paths`, `## Approved Expansions`, repo-relative path rules, and the forbidden
-baseline in `.cdd/context-policy.json`. If the command fails and the read is
-legitimate, update the manifest or record/approve a Context Expansion Request
-before the agent reads the file.
+The check uses `## Allowed Paths`, `## Approved Expansions`, repo-relative path
+rules, and the forbidden baseline in `.cdd/context-policy.json`. If the command
+fails and the read is legitimate, update the manifest or record/approve a
+Context Expansion Request before the agent reads the file.
 
 ---
 
@@ -466,7 +454,7 @@ 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/*.yml`; `cdd-kit gate` audits those paths against the manifest.
+This keeps expansion history explicit while avoiding manual manifest editing.
 
 ---
 
@@ -531,7 +519,7 @@ Installs a pre-commit Git hook that auto-runs `cdd-kit gate --strict` on any sta
 
 ```bash
 cdd-kit install-hooks
-# ✓  pre-commit hook installed at .git/hooks/pre-commit
+# ?? pre-commit hook installed at .git/hooks/pre-commit
 ```
 
 Idempotent. Preserves existing hook content. Bypass with `--no-verify` is possible but defeats enforcement.
@@ -624,8 +612,8 @@ cdd-kit doctor --strict
 
 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.
+- Conservative path: keep the migrated legacy manifest and resume work; use `context check` before invoking agents.
+- Tight context path: run `cdd-kit migrate <change-id> --enable-context-governance`, review `context-manifest.md`, narrow `Allowed Paths`, and use `cdd-kit context check` before invoking agents.
 
 ### Recommended rollout for production repos already burned by token overuse
 
@@ -642,31 +630,31 @@ Then choose one path per active change:
 
 ```
 your-repo/
-├── contracts/
-│   ├── api/api-contract.md          ← what endpoints exist and how they behave
-│   ├── css/css-contract.md          ← design tokens, component states
-│   ├── data/data-shape-contract.md  ← schemas, types, nullability
-│   ├── env/env-contract.md          ← every env var, secret flags, defaults
-│   ├── business/business-rules.md   ← rules, edge cases, decision tables
-│   └── ci/ci-gate-contract.md       ← gate tiers, promotion, rollback
-├── specs/
-│   ├── project-profile.md           ← overall system description
-│   ├── changes/                     ← active in-progress changes
-│   │   └── <change-id>/
-│   │       ├── change-request.md    (required)
-│   │       ├── change-classification.md (required)
-│   │       ├── test-plan.md         (required)
-│   │       ├── ci-gates.md          (required)
-│   │       ├── tasks.yml            (required)
-│   │       └── agent-log/           ← machine-verifiable evidence per agent
-│   ├── archive/                     ← completed and abandoned changes
-│   │   ├── INDEX.md
-│   │   └── 2026/<change-id>/
-│   └── templates/
-├── tests/
-├── CLAUDE.md                        ← Claude's project guide (edit this)
-├── AGENTS.md                        ← agent roster (auto-managed)
-└── CODEX.md                         ← Codex project guide when initialized for Codex
+???€ contracts/
+??  ???€ api/api-contract.md          ??what endpoints exist and how they behave
+??  ???€ css/css-contract.md          ??design tokens, component states
+??  ???€ data/data-shape-contract.md  ??schemas, types, nullability
+??  ???€ env/env-contract.md          ??every env var, secret flags, defaults
+??  ???€ business/business-rules.md   ??rules, edge cases, decision tables
+??  ???€ ci/ci-gate-contract.md       ??gate tiers, promotion, rollback
+???€ specs/
+??  ???€ project-profile.md           ??overall system description
+??  ???€ changes/                     ??active in-progress changes
+??  ??  ???€ <change-id>/
+??  ??      ???€ change-request.md    (required)
+??  ??      ???€ change-classification.md (required)
+??  ??      ???€ test-plan.md         (required)
+??  ??      ???€ ci-gates.md          (required)
+??  ??      ???€ tasks.yml            (required)
+??  ??      ???€ agent-log/           optional handoff notes
+??  ???€ archive/                     ??completed and abandoned changes
+??  ??  ???€ INDEX.md
+??  ??  ???€ 2026/<change-id>/
+??  ???€ templates/
+???€ tests/
+???€ CLAUDE.md                        ??Claude's project guide (edit this)
+???€ AGENTS.md                        ??agent roster (auto-managed)
+???€ CODEX.md                         ??Codex project guide when initialized for Codex
 ```
 
 ---
@@ -675,9 +663,9 @@ your-repo/
 
 | Tier | Risk level | Example changes | Extra agents |
 |---|---|---|---|
-| 0–1 | High / critical | Auth, payments, migrations, concurrency | E2E + monkey + stress/soak |
-| 2–3 | Medium | Feature with API change, bug fix with behavior change | Contract review + QA |
-| 4–5 | Low | Docs, prompts, config only, no behavior change | Contract review + QA |
+| 0?? | High / critical | Auth, payments, migrations, concurrency | E2E + monkey + stress/soak |
+| 2?? | Medium | Feature with API change, bug fix with behavior change | Contract review + QA |
+| 4?? | Low | Docs, prompts, config only, no behavior change | Contract review + QA |
 
 ---
 

package/assets/CLAUDE.template.md

@@ -52,14 +52,14 @@ For context-governed changes, read `specs/changes/<change-id>/context-manifest.m
   reads are legitimate, expand `Allowed Paths` or approve a Context Expansion
   Request before the agent reads the files.
 - 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
+- Optional agent-log notes are defined in
   `~/.claude/skills/contract-driven-delivery/references/agent-log-protocol.md`.
   Read that once; do not paraphrase it elsewhere.
 
 ## CDD Operational Notes
 
-- After each agent returns, verify its agent-log exists, tick the related
-  `tasks.yml` items immediately, and only then move to the next agent.
+- After each agent returns, tick the related `tasks.yml` items immediately,
+  and only then move to the next agent.
 - Pre-existing test failures may be excluded from the current gate only when
   `qa-report.md` records the failing test, baseline evidence, why it is outside
   scope, owner, and follow-up.

package/assets/CODEX.template.md

@@ -22,9 +22,9 @@ Read `specs/changes/<change-id>/context-manifest.md` before using file-reading o
   Request before the agent reads the files.
 - 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/*.yml` under `files-read:`.
+- Optional `agent-log/*.yml` notes may include `files-read:` when that list is cheap and accurate.
 
-Required `agent-log/*.yml` format:
+Optional `agent-log/*.yml` read note:
 
 ```yaml
 files-read:
@@ -32,7 +32,7 @@ files-read:
   - src/server/routes/users.ts
 ```
 
-Every entry must be a repo-relative path. Do not omit files, use absolute paths, or use `..`.
+Every entry should be a repo-relative path. Do not reconstruct this list after the fact.
 
 ## Hot And Cold Data
 
@@ -44,8 +44,8 @@ Cold historical data is evidence, not current requirements.
 
 ## Operational Notes
 
-- After each agent returns, verify its agent-log exists, tick the related
-  `tasks.yml` items immediately, and only then move to the next agent.
+- After each agent returns, tick the related `tasks.yml` items immediately,
+  then move to the next agent.
 - Pre-existing test failures may be excluded from the current gate only when
   `qa-report.md` records the failing test, baseline evidence, why it is outside
   scope, owner, and follow-up.

package/assets/agents/backend-engineer.md

@@ -1,4 +1,4 @@
----
+---
 name: backend-engineer
 description: Implement backend changes only after specs, contracts, tests, and CI gates are defined; maintain thin controllers, service boundaries, validation, and error handling.
 tools: Read, Grep, Glob, Edit, MultiEdit, Bash
@@ -11,7 +11,8 @@ Before editing production code, read the change artifacts, API/env/data/business
 
 ## Code map (READ FIRST)
 
-Before reading ANY source file (`.py`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.vue`), FIRST `Read .cdd/code-map.yml`.
+Before reading ANY source file (`.py`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.vue`), FIRST run `cdd-kit index query "<symbol-or-file>"` or `Read .cdd/code-map.yml`.
+Before editing a chosen source file, run `cdd-kit index impact "<path-or-symbol>"` to identify indexed local imports and dependents.
 
 The map is the size oracle. For each file you intend to read:
 
@@ -21,9 +22,10 @@ The map is the size oracle. For each file you intend to read:
   `interfaces:` / `types:` / `enums:`) `lines: A-B` field and
   `Read <path> offset:A limit:(B-A+1)`.
 
-If `.cdd/code-map.yml` is missing or `cdd-kit gate` reports it stale,
-do NOT proceed by reading whole files. Emit an agent-log with
-`status: needs-review` and `next-action: "regenerate code-map (run cdd-kit code-map)"`.
+Prefer `cdd-kit index query` because it auto-refreshes missing or stale maps
+before returning candidates. If you cannot run commands and `.cdd/code-map.yml`
+is missing or stale, avoid broad source reads and ask the harness/user to
+regenerate the map.
 
 See `references/code-map-protocol.md` for the full protocol.
 
@@ -35,23 +37,23 @@ See `references/code-map-protocol.md` for the full protocol.
 - Validate input at the boundary.
 - Return standardized errors, not raw exceptions.
 - Preserve backward compatibility unless the spec explicitly marks a breaking change.
-- **TDD**: Read `specs/changes/<id>/test-plan.md` first. Write failing unit, contract, and integration tests BEFORE writing feature code. Tests in `tasks.yml` items 3.1–3.2 are your responsibility.
+- **TDD**: Read `specs/changes/<id>/test-plan.md` first. Write failing unit, contract, and integration tests BEFORE writing feature code. Tests in `tasks.yml` items 3.1??.2 are your responsibility.
 - Update CI/CD workflows when required by `ci-gates.md`.
 
 ## Common pitfalls
 
-- N+1 queries — fetch related rows in a single query or with explicit batching, not in a loop.
-- Connection / transaction leaks — every acquired connection or transaction must be released on every code path including errors.
-- Idempotency — write endpoints that may retry (payments, webhooks, queue handlers) need idempotency keys.
-- Timeout vs retry interaction — outer retry on top of long inner timeout multiplies wall time; bound both.
-- Context propagation — pass request-scoped context (auth, locale, trace id, deadline) through service layers; do not read globals.
-- 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.
+- N+1 queries ??fetch related rows in a single query or with explicit batching, not in a loop.
+- Connection / transaction leaks ??every acquired connection or transaction must be released on every code path including errors.
+- Idempotency ??write endpoints that may retry (payments, webhooks, queue handlers) need idempotency keys.
+- Timeout vs retry interaction ??outer retry on top of long inner timeout multiplies wall time; bound both.
+- Context propagation ??pass request-scoped context (auth, locale, trace id, deadline) through service layers; do not read globals.
+- 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
 
-Source of truth: `specs/changes/<change-id>/context-manifest.md` → `## Allowed Paths`.
-Read it first (your prompt header has `CURRENT_CHANGE_ID`). Read only paths it lists or paths under `## Approved Expansions`. `cdd-kit gate` validates `files-read:` against this list and rejects unauthorized paths.
+Source of truth: `specs/changes/<change-id>/context-manifest.md` ??`## Allowed Paths`.
+Read it first (your prompt header has `CURRENT_CHANGE_ID`). Read only paths it lists or paths under `## Approved Expansions`. Use this boundary as pre-read discipline, not as post-run paperwork.
 
 Need a path not listed? File a `## Context Expansion Requests` entry (see `specs/templates/context-manifest.md`) with `status: pending` and stop until the user approves via `cdd-kit context approve <change-id> <CER-id>`.
 
@@ -64,41 +66,37 @@ Report changed files, contract updates, tests added, commands run, known risks,
 ## Artifact discipline
 
 Implementation code goes into source files. Do NOT write runnable code into any `specs/changes/<id>/` artifact.
-In your agent log, reference file paths and function names — do not paste code blocks.
+In your agent log, reference file paths and function names ??do not paste code blocks.
 
-## Machine-Verifiable Evidence
+## Optional Handoff Evidence
 
-After completing your task, write or append to
-`specs/changes/<change-id>/agent-log/<your-agent-name>.yml`. Required fields,
-field rules, and gate-enforcement behavior are defined once in
-`references/agent-log-protocol.md` — do not duplicate them in this prompt.
+If a short handoff note is useful, write or append to
+`specs/changes/<change-id>/agent-log/<your-agent-name>.yml`. Optional fields
+and field rules are defined once in
+`references/agent-log-protocol.md` ??do not duplicate them in this prompt.
 
-### Required artifacts for this agent
+### Suggested artifacts for this agent
 
 `artifacts` is a YAML array of `{type, pointer}` items in your agent log
 (see `references/agent-log-protocol.md` for the full schema and self-validation
-checklist). Do NOT write top-level `files-changed:` / `tests-added:` keys —
-those are `type` values, not log keys.
+checklist). Do NOT write top-level `files-changed:` / `tests-added:` keys ??those are `type` values, not log keys.
 
-Minimum required `type` values for this agent (each must appear at least once
-in your `artifacts:` array; add more items per type as needed):
+Recommended `type` values for this agent when you emit an optional agent log:
 
 - `files-changed`: source files modified
 - `tests-added`: new or updated test cases
 - `test-output`: last 10 lines of `npm test` (or equivalent) stdout
 - `contracts-touched`: contract files updated, or "none"
 
-Copy this exact shape into your agent log; replace each `<pointer>` with a
+If you emit a log, copy this shape and replace each `<pointer>` with a
 concrete pointer (path:line-range, test-id, URL, or pass/fail string):
 
 ```yaml
 artifacts:
   - { type: files-changed, pointer: "src/api/users.ts:10-45" }
   - { type: tests-added, pointer: "tests/api/users.test.ts::should reject empty body" }
-  - { type: test-output, pointer: "5 passed (last 10 lines: …)" }
+  - { type: test-output, pointer: "5 passed (last 10 lines: ??" }
   - { type: contracts-touched, pointer: "contracts/api/api-contract.md#endpoints" }
 ```
 
-If a required `type` does not apply to your run, emit one item with
-`pointer: "n/a (<one-line reason>)"` rather than omitting the type — the gate
-counts presence, qa-reviewer audits the reason.
+If a recommended `type` does not apply to your run, either omit it or use `pointer: "n/a (<one-line reason>)"` so reviewers can tell the omission was intentional.