contract-driven-delivery 2.0.12 → 2.0.13

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [2.0.13] - 2026-05-05
+
+Documentation and release-prep patch focused on keeping CDD low-friction.
+
+### Changed
+
+- **Clarified workflow lanes**: README now distinguishes full tracked CDD
+  changes from maintenance / micro-change work, so typo fixes, formatting,
+  lint-only changes, and tiny local repairs do not imply proposal-level
+  ceremony.
+- **Documented future machine-readable metadata direction**:
+  `docs/machine-readable-change-design.md` defines `change.yml` and
+  `trace.yml` as generated metadata for reducing markdown parsing and token
+  use, not as new manually-authored forms.
+- **Synced skill/protocol docs with implementation**: `/cdd-new` now reflects
+  that `context-manifest.md` is required and that `cdd-kit new` auto-runs
+  `context-scan` when indexes are missing or stale; the agent-log protocol now
+  reflects that gate enforces per-agent artifact types when prompt files are
+  installed.
+
 ## [2.0.12] - 2026-05-04
 
 Tiny patch — closes the last line-ending hole.

package/README.md

@@ -99,6 +99,21 @@ or
 8. `cdd-kit gate <change-id>` runs automatically to confirm all artifacts are complete
 9. Claude reports a summary and the suggested git commit
 
+### Workflow Lanes: Avoiding Ceremony for Small Fixes
+
+CDD is a governance workflow, not a rule that every edit must become a full proposal. Use the tracked `/cdd-new` flow when a change can affect product behavior, contracts, data shape, API behavior, env/deploy rules, CI/CD, security, permissions, cross-module architecture, or release risk.
+
+Use a lightweight maintenance lane for small corrections where the intent is already obvious:
+
+| 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` |
+
+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.
+
+Machine-readable metadata such as future `change.yml` / `trace.yml` should follow the same rule: generated from existing artifacts to reduce token use and markdown parsing, not introduced as extra forms. See `docs/machine-readable-change-design.md` for the proposed shape.
+
 ### Agent Ownership Model
 
 CDD uses two agent classes on purpose:

package/assets/skills/cdd-new/SKILL.md

@@ -106,7 +106,7 @@ Note: `archive.md` is created during `/cdd-close`, not during `/cdd-new` — it
 
 If the classifier marks an artifact as `no` or leaves it blank, **do not create the file** — even if a review agent could contribute to it.
 
-The 5 always-required artifacts are: `change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.yml`.
+The 6 always-required artifacts are: `change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.yml`, and `context-manifest.md`.
 
 ## Step 1: Generate change-id, scaffold, and scan context
 
@@ -122,17 +122,19 @@ Create the scaffold with the CLI so every provider gets the same templates:
 cdd-kit new <change-id>
 ```
 
-Then build deterministic context indexes before invoking any classifier:
-
-```bash
-cdd-kit context-scan
-```
+`cdd-kit new` auto-runs `cdd-kit context-scan` when `specs/context/` indexes are missing or stale. Do not run a second scan unless the command warned that context-scan failed, or you intentionally used `--skip-scan`.
 
 Verify these files exist:
 - `specs/changes/<change-id>/context-manifest.md`
 - `specs/context/project-map.md`
 - `specs/context/contracts-index.md`
 
+If either context index is still missing, run:
+
+```bash
+cdd-kit context-scan
+```
+
 Do not use broad search or ad hoc reads to classify the change before `context-scan` has completed.
 
 The generated scaffold contains the artifacts listed in the table below. **All

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

@@ -80,9 +80,16 @@ can act on. When `status: complete`, `none` is acceptable.
 ## Per-agent additional artifact requirements
 
 Each agent prompt lists its own `### Required artifacts for this agent`. The
-gate does not enforce those today; they are a discipline contract enforced by
-`qa-reviewer` and `contract-reviewer`. If you add a required artifact in an
-agent prompt, also update the qa-reviewer checklist.
+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
 
@@ -132,7 +139,8 @@ ship a known-bad log and rely on the gate to catch it.
 5. `files-read` is missing for a context-governed change, or contains an
    absolute path / `..` segment / forbidden path.
 6. Any `artifacts` item is missing `type` or `pointer`, or the array is empty.
-7. With `--strict`: any `artifacts` pointer that looks like a path but does
+7. A required per-agent artifact `type` declared in the agent prompt is missing.
+8. With `--strict`: any `artifacts` pointer that looks like a path but does
    not exist on disk; or any runtime-logged read not declared in `files-read`.
 
 ## Why this lives in references/

package/docs/machine-readable-change-design.md

@@ -0,0 +1,137 @@
+# Machine-Readable Change Metadata Design
+
+## Goal
+
+`change.yml` and `trace.yml` should reduce markdown parsing and repeated agent
+reads. They must not become new forms humans must fill out before making small
+fixes.
+
+The design principle is:
+
+- Humans write normal change artifacts only when a tracked CDD change is useful.
+- Tools derive machine-readable state from existing artifacts whenever possible.
+- Missing machine-readable files should be fixable by regeneration, not by
+  forcing a user through extra ceremony.
+
+## Workflow Lanes
+
+| lane | when to use | metadata expectation |
+|---|---|---|
+| maintenance / micro-change | typo fixes, docs cleanup, formatting, lint-only fixes, tiny local test repair | no `specs/changes/<id>/` required |
+| tracked CDD change | behavior, contract, API, data, env, security, CI/CD, cross-module, or release-risk work | `change.yml` and `trace.yml` generated under `specs/changes/<id>/` |
+
+The kit should not enforce "every hot file edit needs a change id" by default.
+Teams that want that policy can add a repo-local hook or CI wrapper, but it
+should not be the baseline behavior.
+
+## `change.yml`
+
+Purpose: a compact state index for one tracked change.
+
+Source of truth:
+
+- `tasks.yml` for status, tier, dependencies, and task state.
+- `change-classification.md` for change type, agents, and acceptance criteria.
+- `context-manifest.md` for read scope.
+- `agent-log/*.yml` for evidence and agent completion.
+
+Generated shape:
+
+```yaml
+change-id: add-jwt-auth
+status: in-progress
+tier: 2
+lane: tracked
+types:
+  primary: feature-enhancement
+  secondary: [api-only-change]
+required-agents:
+  - change-classifier
+  - test-strategist
+  - backend-engineer
+  - contract-reviewer
+  - qa-reviewer
+artifacts:
+  required:
+    - change-request.md
+    - change-classification.md
+    - test-plan.md
+    - ci-gates.md
+    - tasks.yml
+    - context-manifest.md
+  optional: []
+context:
+  manifest: specs/changes/add-jwt-auth/context-manifest.md
+  allowed-paths-count: 8
+dependencies: []
+generated-from:
+  tasks.yml: sha256:<digest>
+  change-classification.md: sha256:<digest>
+  context-manifest.md: sha256:<digest>
+```
+
+Rules:
+
+- `change.yml` is generated by the CLI, not hand-authored.
+- If it is absent, agents may fall back to existing markdown/YAML artifacts.
+- `cdd-kit doctor --fix` is the right place to regenerate stale metadata.
+- `cdd-kit gate` may warn on stale metadata, but should not fail only because
+  `change.yml` is missing unless a repo opts into strict metadata mode.
+
+## `trace.yml`
+
+Purpose: a compact traceability graph from acceptance criteria to evidence.
+
+Source of truth:
+
+- Acceptance criteria from `change-classification.md`.
+- Test mapping from `test-plan.md`.
+- CI gates from `ci-gates.md`.
+- Evidence pointers from `agent-log/*.yml`.
+
+Generated shape:
+
+```yaml
+change-id: add-jwt-auth
+criteria:
+  - id: AC-1
+    text: Users can log in with a valid JWT.
+    tests:
+      - family: integration
+        path: tests/auth/login.test.ts
+        name: accepts valid token
+    gates:
+      - unit
+      - contract
+    evidence:
+      - agent: backend-engineer
+        type: tests-added
+        pointer: tests/auth/login.test.ts::accepts valid token
+      - agent: qa-reviewer
+        type: qa-verdict
+        pointer: specs/changes/add-jwt-auth/agent-log/qa-reviewer.yml
+```
+
+Rules:
+
+- `trace.yml` is generated from existing evidence.
+- It should help reviewers and agents avoid rereading long markdown files.
+- Missing evidence should point back to the existing artifact that needs work;
+  it should not introduce a new place to manually duplicate the same content.
+
+## CLI Direction
+
+Useful future commands:
+
+```bash
+cdd-kit metadata <change-id>        # regenerate change.yml and trace.yml
+cdd-kit metadata <change-id> --check
+cdd-kit doctor --fix                # regenerate stale metadata for active changes
+```
+
+Default gate behavior should stay low-friction:
+
+- Warn when generated metadata is stale or absent.
+- Fail only when source artifacts themselves are invalid.
+- Add a repo opt-in for strict metadata enforcement later if teams ask for it.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contract-driven-delivery",
-  "version": "2.0.12",
+  "version": "2.0.13",
   "description": "Contract-driven delivery kit for AI coding agents with deterministic context indexes, manifest-backed read-scope governance, and orchestrated contracts-first delivery.",
   "keywords": [
     "contract-driven",