contract-driven-delivery 2.0.16 → 2.0.17

package/assets/skills/contract-driven-delivery/references/agent-log-protocol.md

@@ -1,72 +1,63 @@
-# Agent Log Protocol (YAML)
+# Agent Log Protocol (Optional YAML)
 
-All cdd-kit agents share the same machine-verifiable agent-log format. This
-file is the single source of truth — agent prompts reference it instead of
-inlining the format. `cdd-kit gate` validates these files against
-`src/schemas/agent-log.schema.ts` (JSON Schema, draft-07). Drift here equals
-silent gate skips, so do not re-document this in agent prompts.
+Agent logs are optional trace artifacts for debugging, resume summaries, and
+handoff notes. They are not required for `cdd-kit gate`, and agents should not
+spend useful development time reconstructing every file they read.
 
-## Output target
+## Output Target
 
-Each agent writes (or has main Claude write) one file per run:
+If an agent emits a log, write one YAML file per run:
 
-```
+```text
 specs/changes/<change-id>/agent-log/<agent-name>.yml
 ```
 
-If the same agent runs more than once for a change (e.g., after fix-back),
-overwrite the file — only the latest run is gate-relevant.
-
-## Required structure
+If the same agent runs more than once for a change, overwrite the file. The
+latest run is the only useful trace.
 
-The file is pure YAML (no markdown wrapping, no checklist).
+## Minimal Structure
 
 ```yaml
 change-id: <id>
 agent: <agent-name>
 timestamp: "<ISO 8601 date-time, e.g. 2026-04-27T14:30:00Z>"
-status: complete            # complete | needs-review | blocked
-files-read:
-  - <repo-relative path>
-  - <repo-relative path>
+status: complete
 artifacts:
   - { type: <evidence-type>, pointer: <concrete pointer> }
-  - { type: <evidence-type>, pointer: <concrete pointer> }
-next-action: <one line, or "none">
+next-action: none
 notes: <optional free-form>
 ```
 
-### Field rules
-
-| field | required | rule |
-|---|---|---|
-| `change-id` | yes | must equal the parent change directory name |
-| `agent` | yes | canonical agent name (matches the agent's filename) |
-| `timestamp` | yes | ISO 8601 date-time string; quote it to avoid YAML timestamp coercion in non-cdd tools. UTC `Z` is preferred; numeric offsets such as `+08:00` are accepted. |
-| `status` | yes | canonical values are `complete` \| `needs-review` \| `blocked`; `done` and `approved` are accepted by gate as compatibility aliases for `complete` |
-| `files-read` | conditional | required for context-governed changes (see below) |
-| `artifacts` | yes | array of `{type, pointer}` objects, ≥ 1 item |
-| `next-action` | yes | when `status: blocked`, ≥ 10 chars and not `none` |
-| `notes` | no | optional |
-
-#### `files-read`
-
-Required when `tasks.yml` has `context-governance: v1`. Each entry is a
-repo-relative path. Absolute paths and `..` traversal are rejected. If you
-legitimately read nothing beyond your own change directory, write:
+Optional fields:
 
 ```yaml
 files-read:
-  - specs/changes/<change-id>/
+  - <repo-relative path>
+indexes-used:
+  - .cdd/code-map.yml
+index-queries:
+  - cdd-kit index query "AuthService"
 ```
 
-If `cdd-kit gate` reports `read unauthorized path`, do not delete that
-`files-read` entry to silence the gate. If the read was legitimate work scope,
-add the repo-relative path to `context-manifest.md` under `## Allowed Paths` or
-approve a Context Expansion Request. `files-read` is the audit trail; the
-manifest is the authorization boundary.
+Use optional fields only when they are cheap and accurate. Do not add noisy
+paperwork just to satisfy a gate; the gate does not inspect these logs.
 
-#### `artifacts`
+## Field Rules
+
+| field | required | rule |
+|---|---|---|
+| `change-id` | yes | should equal the parent change directory name |
+| `agent` | yes | canonical agent name, matching the agent filename |
+| `timestamp` | yes | ISO 8601 date-time string; quote it to avoid YAML timestamp coercion |
+| `status` | yes | `complete` \| `needs-review` \| `blocked` |
+| `artifacts` | yes | concise array of `{type, pointer}` objects |
+| `next-action` | yes | when `status: blocked`, name the concrete next step |
+| `files-read` | no | optional repo-relative read trace |
+| `indexes-used` | no | optional repo-relative index artifact paths used to plan reads |
+| `index-queries` | no | optional command/query strings used for project intelligence |
+| `notes` | no | optional |
+
+## artifacts
 
 Concrete pointers only. Allowed forms:
 
@@ -75,123 +66,43 @@ Concrete pointers only. Allowed forms:
 - `cdd-kit gate <id>: 0 errors`
 - `contracts/api/api-contract.md#endpoints`
 
-Gate path-existence rule: unless gate is run with `--lax`, any pointer whose
-text before the first `:` contains `/` is treated as a repo-relative file path
-and that file must exist. This makes path-like pointers useful, but it also
-means:
+Pointer style still matters because humans and future tools may parse these
+values. When the text before the first `:` contains `/`, treat it as one
+repo-relative file path:
 
 - One pointer names one file only. Use separate `artifacts` items for multiple
   files.
 - Do not attach parenthetical notes to a file path, e.g. use
   `src/api/users.ts:45-67`, not `src/api/users.ts (updated):45-67`.
 - Do not start a pointer with slash-containing prose labels such as `I/O:` or
-  `WARNING/OVERDUE:`; gate will try to validate `I/O` or `WARNING/OVERDUE` as a
-  path. Write those labels in `notes` or after a non-path command/result
-  pointer.
-- `n/a (<reason>)` is exempt from path validation and is allowed for genuinely
-  inapplicable required artifact types.
-
-Never `verified`, `OK`, `done`, or unscoped prose.
-
-#### `next-action`
-
-When `status: blocked`, this must be ≥ 10 chars, must not be `none`, `tbd`,
-`investigate further`, or `n/a`, and must name the actual next step a human
-can act on. When `status: complete`, `none` is acceptable.
-
-#### `status`
-
-Use `status: complete` for a finished agent-log. `tasks.yml` task entries use
-`status: done`, and review language may say "approved", but agent-log
-completion is canonically `complete`. `cdd-kit gate` accepts `done` and
-`approved` as compatibility aliases so these common mix-ups do not block
-delivery.
-
-## Per-agent additional artifact requirements
-
-Each agent prompt lists its own `### Required artifacts for this agent`. The
-gate enforces the declared artifact `type` values when the corresponding agent
-prompt file is installed in `.claude/agents/` or `~/.claude/agents/`. This keeps
-agent prompts, evidence logs, and gate behavior aligned without duplicating the
-full protocol in every prompt.
-
-If you add a required artifact type in an agent prompt, also update tests that
-exercise `cdd-kit gate` for that agent. Agents may emit
-`pointer: "n/a (<reason>)"` when a declared type is genuinely inapplicable; the
-type must still be present so reviewers can tell that the omission was
-intentional.
-
-## Self-validation before submitting your response
-
-**Every agent MUST self-validate its draft agent-log YAML before finishing.**
-A malformed log forces `cdd-kit gate` to fail, which forces the skill to
-re-invoke you, which costs the user another full agent round. Self-lint is
-~5 seconds; a re-run is minutes and dollars.
-
-Before sending your final response, re-read the YAML you intend to write and
-verify each item:
-
-- [ ] **All required keys exist**: `change-id`, `agent`, `timestamp`,
-      `status`, `artifacts`, `next-action` (plus `files-read` for
-      context-governed changes).
-- [ ] **`timestamp` is quoted** and uses ISO 8601 date-time form. Prefer
-      UTC `Z`, e.g. `timestamp: "2026-04-27T14:30:00Z"`. Numeric offsets
-      such as `timestamp: "2026-05-05T00:00:00+08:00"` are valid.
-- [ ] **`status` is one of**: `complete`, `needs-review`, `blocked`.
-      Prefer `complete` for finished logs; `done` and `approved` are accepted
-      only as compatibility aliases. Do not use `OK`, `pending`, `wip`, or
-      anything else.
-- [ ] **Every `artifacts` item is a `{type, pointer}` mapping** with a
-      concrete pointer:
-      - GOOD: `{ type: tests-added, pointer: "tests/foo.test.ts::should reject empty body" }`
-      - GOOD: `{ type: files-changed, pointer: "src/api/users.ts:45-67" }`
-      - GOOD: `{ type: test-output, pointer: "5 passed (last 10 lines: …)" }`
-      - BAD: `{ type: tests-added, pointer: verified }`
-      - BAD: `{ type: files-changed, pointer: yes }`
-      - BAD: `{ type: contract, pointer: OK }`
-      - BAD: `{ type: files-changed, pointer: "src/api/users.ts (updated):45-67" }`
-      - BAD: `{ type: test-output, pointer: "I/O: warning reproduced" }`
-      - BAD: `{ type: test-output, pointer: "WARNING/OVERDUE: manual follow-up" }`
-      Reject any line whose pointer would not let a reviewer click through.
-      If the text before the first `:` contains `/`, confirm it is exactly one
-      existing repo-relative file path with no parenthetical note.
-- [ ] **If `status: blocked`**, `next-action` is ≥ 10 chars, is NOT `none`,
-      `investigate further`, `tbd`, or `n/a`, and names the actual next step
-      a human can act on.
-- [ ] **Every `files-read` entry**: repo-relative path, no leading `/`, no
-      `..`, no `~`. If you read your own change directory only, write
-      `- specs/changes/<change-id>/`.
-- [ ] **YAML is parseable**: indentation is consistent (2 spaces), strings
-      with special characters (`:`, `#`, leading numbers like `001`) are
-      quoted.
-
-If any check fails, **fix the YAML before sending your response**. Do not
-ship a known-bad log and rely on the gate to catch it.
-
-## Gate enforcement summary
-
-`cdd-kit gate` rejects an agent log when any of these are true:
-
-1. The file is missing for a tier-required agent (see CONTRACTS for tier matrix).
-2. YAML fails to parse, or top-level is not a mapping.
-3. `status` is missing or has an unknown value.
-4. `status: blocked` without a concrete `next-action`.
-5. `files-read` is missing for a context-governed change, or contains an
-   absolute path / `..` segment / forbidden path / path outside manifest
-   `Allowed Paths` and `Approved Expansions`.
-6. Any `artifacts` item is missing `type` or `pointer`, or the array is empty.
-7. A required per-agent artifact `type` declared in the agent prompt is missing.
-8. Unless gate is run with `--lax`: any `artifacts` pointer whose text before
-   the first `:` contains `/` but does not exist on disk; or any
-   runtime-logged read not declared in `files-read`.
-
-## Why this lives in references/
+  `WARNING/OVERDUE:`. Write those labels in `notes` or after a non-path
+  command/result pointer.
+- `n/a (<reason>)` is allowed for genuinely inapplicable artifact types.
 
-The historical mistake was duplicating the protocol inside every agent prompt.
-Sixteen agents × ~30 lines = ~480 lines of identical text loaded on every
-spawn. Moving it here:
+Never use `verified`, `OK`, `done`, or unscoped prose as evidence pointers.
+
+## next-action
 
-- Cuts per-agent prompt size by 25–35%.
-- Makes drift between agents impossible (one file to change).
-- Lets gate.ts behavior, schemas, tests, and prompts stay in sync via this
-  single doc.
+When `status: blocked`, this must be concrete and must not be `none`, `tbd`,
+`investigate further`, `unknown`, `todo`, or `n/a`. When `status: complete`,
+`none` is acceptable.
+
+## Self-Validation
+
+If you choose to emit an agent log, self-validate it before finishing:
+
+- Required keys exist: `change-id`, `agent`, `timestamp`, `status`,
+  `artifacts`, `next-action`.
+- `timestamp` is quoted and uses ISO 8601 date-time form.
+- `status` is one of `complete`, `needs-review`, `blocked`.
+- Every `artifacts` item is a `{type, pointer}` mapping with a concrete pointer.
+- If `status: blocked`, `next-action` names the actual next step.
+- Optional `files-read` entries are repo-relative, with no leading `/`, no
+  `..`, and no `~`.
+- YAML is parseable with consistent two-space indentation.
+
+## Why This Lives In References
+
+The historical mistake was duplicating the protocol inside every agent prompt.
+Moving it here cuts prompt size and keeps optional traces consistent without
+turning them into required process paperwork.

package/assets/skills/contract-driven-delivery/references/code-map-protocol.md

@@ -1,53 +1,75 @@
 # Code Map Protocol
 
-`.cdd/code-map.yml` is a deterministic structural index of every source
-file in the repo (`.py`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`,
-`.vue`). Generated by `cdd-kit code-map`, committed to git, refreshed
-automatically when `cdd-kit init --hooks` is installed. `cdd-kit gate`
-hard-fails when any source file is newer than the map.
+`.cdd/code-map.yml` is a deterministic structural index of every source file
+in the repo (`.py`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.vue`).
+Generated by `cdd-kit code-map`, committed to git, refreshed automatically
+when `cdd-kit init --hooks` is installed. `cdd-kit gate` does not enforce
+index hygiene; use `cdd-kit code-map --check`, `cdd-kit doctor --fix`, or the
+auto-refreshing `cdd-kit index ...` commands for that job.
 
-## Why agents must read it FIRST
+## Preferred workflow: query before reading
+
+Before reading source, run a targeted query:
+
+```bash
+cdd-kit index query "AuthService"
+cdd-kit index query "users.ts" --limit 5
+cdd-kit index impact "src/services/auth.ts"
+```
+
+`cdd-kit index query` searches file paths, imports, constants, classes,
+methods, functions, interfaces, types, enums, and enum members. It also
+auto-regenerates `.cdd/code-map.yml` when the map is missing or stale, then
+prints only the candidate files and line ranges an agent should inspect first.
+
+Before editing a source file, run `cdd-kit index impact "<path-or-symbol>"`.
+It reports indexed local imports and direct dependents, so the agent can inspect
+the target plus likely affected callers/callees before changing behavior.
 
 Agents have no built-in way to know a file's line count before reading it.
-Reading a 1300-line file when you only need lines 200–250 wastes 80%+
-of the token budget. The code map is the size oracle: it tells you how
-big a file is and exactly which lines hold the symbol you need.
+Reading a 1300-line file when you only need lines 200-250 wastes most of the
+token budget. The code map is the size oracle: it tells you how big a file is
+and exactly which lines hold the symbol you need.
 
 ## The 300-line rule
 
 Before reading any source file:
 
-1. `Read .cdd/code-map.yml` once at the start of your task (cache it for
-   the rest of your session).
-2. Find the file's entry. The first line is `<path>:  # N lines`.
-3. If `N <= 300`: do a normal full `Read <path>`.
-4. If `N > 300`: locate the class / method / function in the entry's
-   `classes:` / `functions:` block (or, for `.ts`/`.tsx`, the
-   `interfaces:` / `types:` / `enums:` blocks); its `lines: A-B`
-   field is the exact range. Use `Read <path> offset:A limit:(B-A+1)`.
-5. To understand a file's surface area without reading code, the
-   `imports:` / `constants:` / `interfaces:` / `types:` sections are
-   usually sufficient.
+1. Prefer `cdd-kit index query "<symbol-or-file>"` to get candidate paths and
+   line ranges.
+2. Before editing a chosen source file, run
+   `cdd-kit index impact "<path-or-symbol>"` to identify local imports and
+   dependents worth inspecting.
+3. If you cannot run commands, `Read .cdd/code-map.yml` once at the start of
+   your task and cache it for the rest of your session.
+4. Find the file's entry. The first line is `<path>:  # N lines`.
+5. If `N <= 300`: do a normal full `Read <path>`.
+6. If `N > 300`: locate the class / method / function in the entry's
+   `classes:` / `functions:` block (or, for `.ts`/`.tsx`, the `interfaces:` /
+   `types:` / `enums:` blocks); its `lines: A-B` field is the exact range. Use
+   `Read <path> offset:A limit:(B-A+1)`.
+7. To understand a file's surface area without reading code, the `imports:` /
+   `constants:` / `interfaces:` / `types:` sections are usually sufficient.
 
 ## Fallback when the map is missing
 
-If `.cdd/code-map.yml` does not exist, do NOT proceed by reading whole
-files. Instead, write an agent-log entry with `status: needs-review`
-and `next-action: "regenerate code-map (run \`cdd-kit code-map\`)"`.
-The user must regenerate the map before you continue. This forces
-attention to missing infrastructure rather than burning tokens
-silently.
+If you can run shell commands, use `cdd-kit index query "<term>"` or
+`cdd-kit index impact "<path-or-symbol>"`; both refresh the map automatically
+before querying. If you cannot run commands and `.cdd/code-map.yml` does not
+exist, avoid broad source reads and ask the harness/user to regenerate the map.
 
 ## Fallback when the map is stale
 
-If `cdd-kit gate` reports `code-map stale`, the map is out of date.
-Same protocol as missing: emit `needs-review`, ask for a regen.
+If you can run shell commands, use `cdd-kit index query "<term>"` or
+`cdd-kit index impact "<path-or-symbol>"`; both refresh stale maps
+automatically. If you cannot run commands and the map is stale, use the same
+protocol as missing: avoid broad source reads and ask for a regen.
 
 ## What the map does NOT contain
 
-- Function bodies, parameter types, JSDoc, TS generic constraints — read
-  the source for these using offset/limit.
-- Vue `<script lang="ts">` blocks — fall back to a full `Read` for now.
+- Function bodies, parameter types, JSDoc, TS generic constraints; read the
+  source for these using offset/limit.
+- Vue `<script lang="ts">` blocks; fall back to a full `Read` for now.
 - Anything inside `node_modules/`, `dist/`, `build/`, `.venv/`, `__pycache__/`.
 
 ## Customising what gets indexed
@@ -56,7 +78,7 @@ Optional file: `.cdd/code-map-config.yml`
 
 ```yaml
 # Both keys optional. When present, each REPLACES (not merges) the built-in
-# default — copy the built-in list and edit it for partial overrides.
+# default; copy the built-in list and edit it for partial overrides.
 include:
   - "**/*.py"
   - "**/*.ts"
@@ -102,6 +124,6 @@ src/types/index.ts:  # 625 lines
       members: [Pending, Active, Done]
 ```
 
-`async ` prefix on a function/method name indicates `async def` (Python)
-or `async function` (JS/TS). `# local` annotation on an interface/type/enum
-means it is NOT exported.
+`async ` prefix on a function/method name indicates `async def` (Python) or
+`async function` (JS/TS). `# local` annotation on an interface/type/enum means
+it is NOT exported.

package/assets/skills/contract-driven-delivery/templates/agent-log.example.yml

@@ -3,9 +3,15 @@ agent: backend-engineer
 timestamp: "2026-04-27T14:30:00Z"
 status: complete
 files-read:
+  - .cdd/code-map.yml
   - contracts/api/api-contract.md
   - src/api/users.ts
   - specs/changes/feat-001/test-plan.md
+indexes-used:
+  - .cdd/code-map.yml
+index-queries:
+  - cdd-kit index query "users.ts"
+  - cdd-kit index impact "src/api/users.ts"
 artifacts:
   - { type: files-changed,     pointer: "src/api/users.ts:45-67" }
   - { type: tests-added,       pointer: "tests/api/users.test.ts::should reject empty body" }

package/assets/skills/contract-driven-delivery/templates/change-classification.md

@@ -69,7 +69,7 @@ Always required: change-request.md, change-classification.md, test-plan.md, ci-g
 ## Context Manifest Draft
 <!-- Classifier fills this section. In /cdd-new Step 2.3, Claude copies it verbatim into
      specs/changes/<change-id>/context-manifest.md, replacing the scaffold.
-     All paths must be repo-relative. Gate enforces Allowed Paths against agent files-read logs. -->
+     All paths must be repo-relative. Use cdd-kit context check before invoking agents. -->
 
 ### Affected Surfaces
 -
@@ -77,7 +77,7 @@ Always required: change-request.md, change-classification.md, test-plan.md, ci-g
 ### Allowed Paths
 <!-- Union of ALL paths any agent will read. Add change-specific paths below the defaults.
      Include component/store/view files for frontend work and CI contracts/workflows for CI work
-     when those files are legitimate work scope. Gate compares agent-log files-read against this list. -->
+     when those files are legitimate work scope. -->
 - specs/changes/<change-id>/
 - specs/context/project-map.md
 - specs/context/contracts-index.md