contract-driven-delivery 2.0.14 → 2.0.15

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [2.0.15] - 2026-05-06
+
+Prompt guidance patch for agent-log evidence and closeout learning ownership.
+
+### Changed
+
+- **Agent-log pointer guidance matches gate behavior**: `/cdd-new` and
+  `agent-log-protocol.md` now spell out that a pointer whose text before the
+  first `:` contains `/` is validated as a single repo-relative file path, so
+  agents avoid parenthetical path notes and slash-containing labels such as
+  `I/O:` or `WARNING/OVERDUE:`.
+- **Durable learning ownership is explicit**: prompts now consistently say
+  general agents record evidence and findings only, while durable learning
+  promotion happens during `/cdd-close` Step 3 and targets `contracts/` or
+  project guidance (`CLAUDE.md`/`CODEX.md`).
+
 ## [2.0.14] - 2026-05-06
 
 Operational hardening for real multi-agent CDD runs.

package/README.md

@@ -190,7 +190,7 @@ 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
-3. Invokes `contract-reviewer` to propose any durable learnings back into `contracts/`
+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/`
 5. Reduces the active context that future Claude sessions need to load
 

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

@@ -10,7 +10,7 @@ description: Close and archive a completed change. Confirms all tasks are done,
 A change is "done" when:
 1. Gate has passed (`cdd-kit gate <change-id>` exits 0)
 2. PR is merged (or change is abandoned)
-3. Durable learnings have been promoted to hot sources: `contracts/`, `CLAUDE.md`, or `CODEX.md`
+3. Durable learnings have been promoted to hot sources: `contracts/` or project guidance (`CLAUDE.md`/`CODEX.md`)
 
 This skill drives steps 2–3 and physically moves the change to `specs/archive/`.
 
@@ -58,7 +58,7 @@ Read `specs/changes/<change-id>/tasks.yml`.
 
 Check section 7:
 - `7.1 Archive change` — will be ticked after Step 4
-- `7.2 Promote durable learnings to contracts or CLAUDE.md` — must be done NOW
+- `7.2 Promote durable learnings to contracts or project guidance` — must be done NOW
 
 If `7.2` is `[ ]`, proceed to Step 2.5. If already `[x]` or `[-]`, skip Steps 2.5 and 3.
 
@@ -92,6 +92,11 @@ This file records the close-out evidence, but Step 3 promotion must still be evi
 
 ## Step 3: Promote learnings (task 7.2)
 
+General agents do not perform durable learning promotion during `/cdd-new`; they
+only record evidence and findings in artifacts and `agent-log/*.yml`. Durable
+learning promotion happens here, during `/cdd-close` Step 3, and main Claude
+owns the final writes.
+
 Read `specs/changes/<change-id>/archive.md` section `## Lessons Promoted to Standards` and cross-check every proposed lesson against agent-log, QA report, contract/test changes, or gate evidence from this change.
 
 Classify each candidate:
@@ -132,7 +137,7 @@ If successful, set task `7.1` to `status: done` in tasks.yml (the file is now in
 
 Change ID: <change-id>
 Archived to: specs/archive/<year>/<change-id>/
-Learnings promoted: <list what was added to contracts/CLAUDE.md/CODEX.md, or "none">
+Learnings promoted: <list what was added to contracts/ or project guidance (CLAUDE.md/CODEX.md), or "none">
 
 specs/changes/<change-id>/ has been removed from the active surface.
 Token cost of future sessions reduced by ~<N> files.

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

@@ -96,6 +96,21 @@ inevitable re-classification when the agents discover the ambiguity.
 
 **Rule**: After EVERY agent completes (whether it writes itself or you write for it), YOU must update the relevant `tasks.yml` task `status:` from `pending` to `done`.
 
+**Agent-log pointer rule**: When you or an agent writes `artifacts[].pointer`,
+follow `references/agent-log-protocol.md` exactly. If the text before the first
+`:` contains `/`, `cdd-kit gate` treats that text as a repo-relative file path
+and verifies that the file exists. Therefore each pointer may name only one
+file, file pointers must not include parenthetical notes on the path, and
+slash-containing labels such as `I/O:` or `WARNING/OVERDUE:` must not be used as
+pointer prefixes. Put extra explanation in `notes` or a separate non-path
+artifact pointer instead.
+
+**Durable learning rule**: During `/cdd-new`, agents record evidence and
+findings in artifacts and `agent-log/*.yml` only. Do not promote durable lessons
+while the change is still active. Durable learning promotion happens only during
+`/cdd-close` Step 3, where main Claude cross-checks evidence and writes approved
+rules to `contracts/` or project guidance (`CLAUDE.md`/`CODEX.md`).
+
 ---
 
 ## Artifact opt-in policy
@@ -515,4 +530,4 @@ Please review the above items and re-run: cdd-kit gate <change-id>
 
 The `/cdd-new` workflow is now complete. **Return to normal assistant mode immediately.** Answer any question the user asks — including questions unrelated to this change, new feature discussions, debugging help, or general conversation — without requiring them to use a specific command. The git commit shown in the report is a suggestion, not a required next step; do not wait for it before resuming normal behavior.
 
-When the change is merged and ready to close, run `/cdd-close <change-id>` to promote learnings and archive the change directory.
+When the change is merged and ready to close, run `/cdd-close <change-id>` to promote durable learnings to `contracts/` or project guidance (`CLAUDE.md`/`CODEX.md`) and archive the change directory.

package/assets/skills/contract-driven-delivery/SKILL.md

@@ -57,7 +57,10 @@ Use this skill to turn software requests into traceable, testable, CI/CD-gated c
    - Invoke ci-cd-gatekeeper to design and enforce the gate plan.
 8. Archive and audit drift.
    - Use `references/spec-drift-policy.md`.
-   - Durable learnings must be promoted back to contracts or CLAUDE.md.
+   - General agents record evidence and findings only; durable learning
+     promotion happens only during `/cdd-close` Step 3.
+   - Durable learnings must be promoted back to `contracts/` or project
+     guidance (`CLAUDE.md`/`CODEX.md`).
    - `spec-drift-auditor` must run before every release to main and weekly during active multi-iteration development.
 
 ## Required gates by risk

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

@@ -75,6 +75,22 @@ 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:
+
+- 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`
@@ -133,7 +149,12 @@ verify each item:
       - 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.
@@ -160,8 +181,9 @@ ship a known-bad log and rely on the gate to catch it.
    `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. 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`.
+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/
 

package/assets/skills/contract-driven-delivery/templates/tasks.yml

@@ -36,4 +36,4 @@ tasks:
   - { id: "6.3", section: Verification, title: "Informational gates", status: pending }
   - { id: "6.4", section: Verification, title: "Nightly/weekly/manual gates if required", status: pending }
   - { id: "7.1", section: Archive, title: "Archive change", status: pending }
-  - { id: "7.2", section: Archive, title: "Promote durable learnings to contracts or CLAUDE.md", status: pending }
+  - { id: "7.2", section: Archive, title: "Promote durable learnings to contracts or project guidance", status: pending }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contract-driven-delivery",
-  "version": "2.0.14",
+  "version": "2.0.15",
   "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",