contract-driven-delivery 2.0.14 → 2.0.16

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## [2.0.16] - 2026-05-06
+
+New-change scaffold hardening so freshly opened proposals use the installed
+kit version even when an existing project has stale templates on disk.
+
+### Changed
+
+- **`cdd-kit new` stamps `tasks.yml` with the real change id**: new changes no
+  longer start with the `<change-id>` placeholder in the machine-validated task
+  metadata.
+
+### Fixed
+
+- **Fresh proposals ignore stale project templates**: regression coverage now
+  locks `cdd-kit new` to bundled package templates, so old
+  `specs/templates/*` files in a user repo cannot leak into a newly created
+  change.
+- **Postinstall sync coverage includes workflow skills**: regression coverage
+  now verifies npm postinstall updates standalone skills such as `/cdd-new`,
+  keeping agent-log instructions aligned with the installed gate.
+
+## [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/dist/cli/index.js

@@ -8678,7 +8678,7 @@ __export(migrate_exports, {
 });
 import { join as join18 } from "path";
 import { cpSync as cpSync2, existsSync as existsSync15, mkdirSync as mkdirSync7, readdirSync as readdirSync8, readFileSync as readFileSync18, renameSync, rmSync as rmSync2, writeFileSync as writeFileSync8 } from "fs";
-import yaml3 from "js-yaml";
+import yaml2 from "js-yaml";
 function backupChangeDir(cwd, changeId, sessionStamp) {
   const backupRoot = join18(cwd, ".cdd", "migrate-backup", sessionStamp);
   const backupDir2 = join18(backupRoot, changeId);
@@ -8854,7 +8854,7 @@ function migrateTasksFile(changeId, changeDir, enableContextGovernance, detected
       out["section"] = r.section;
     return out;
   });
-  const yamlOut = yaml3.dump(data, { lineWidth: -1, noRefs: true });
+  const yamlOut = yaml2.dump(data, { lineWidth: -1, noRefs: true });
   pendingWrites.push({ path: newPath, content: yamlOut });
   pendingDeletes.push({ path: legacyPath });
   changed.push(`tasks.md -> tasks.yml (${tasksRows.length} task(s) migrated)`);
@@ -8922,7 +8922,7 @@ function migrateAgentLogs(changeDir, changed, pendingWrites, pendingDeletes) {
       continue;
     const raw = readFileSync18(fullPath, "utf8");
     const parsed = parseLegacyAgentLog(raw);
-    const yamlOut = yaml3.dump(parsed, { lineWidth: -1, noRefs: true });
+    const yamlOut = yaml2.dump(parsed, { lineWidth: -1, noRefs: true });
     pendingWrites.push({ path: yamlFull, content: yamlOut });
     pendingDeletes.push({ path: fullPath });
     changed.push(`agent-log/${f} -> agent-log/${yamlName}`);
@@ -10146,7 +10146,7 @@ __export(archive_exports, {
 });
 import { join as join23 } from "path";
 import { existsSync as existsSync19, mkdirSync as mkdirSync10, renameSync as renameSync2, readFileSync as readFileSync23, writeFileSync as writeFileSync11, appendFileSync, cpSync as cpSync3, rmSync as rmSync3 } from "fs";
-import yaml4 from "js-yaml";
+import yaml3 from "js-yaml";
 async function archive(changeId) {
   const cwd = process.cwd();
   const changeDir = join23(cwd, "specs", "changes", changeId);
@@ -10166,7 +10166,7 @@ async function archive(changeId) {
   if (existsSync19(tasksPath)) {
     try {
       const raw = readFileSync23(tasksPath, "utf8");
-      const data = yaml4.load(raw);
+      const data = yaml3.load(raw);
       if (data?.status === "gate-blocked") {
         log.warn("tasks.yml has status: gate-blocked \u2014 archiving anyway (change was paused).");
       }
@@ -10222,7 +10222,7 @@ __export(abandon_exports, {
 });
 import { join as join24 } from "path";
 import { existsSync as existsSync20, readFileSync as readFileSync24, writeFileSync as writeFileSync12, appendFileSync as appendFileSync2, mkdirSync as mkdirSync11 } from "fs";
-import yaml5 from "js-yaml";
+import yaml4 from "js-yaml";
 async function abandon(changeId, opts) {
   const cwd = process.cwd();
   const changeDir = join24(cwd, "specs", "changes", changeId);
@@ -10233,12 +10233,12 @@ async function abandon(changeId, opts) {
   }
   if (existsSync20(tasksPath)) {
     const raw = readFileSync24(tasksPath, "utf8");
-    const data = yaml5.load(raw) ?? {};
+    const data = yaml4.load(raw) ?? {};
     data["status"] = "abandoned";
     if (!data["change-id"]) {
       data["change-id"] = changeId;
     }
-    writeFileSync12(tasksPath, yaml5.dump(data, { lineWidth: -1, noRefs: true }), "utf8");
+    writeFileSync12(tasksPath, yaml4.dump(data, { lineWidth: -1, noRefs: true }), "utf8");
   }
   const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   const archiveDir = join24(cwd, "specs", "archive");
@@ -10276,7 +10276,7 @@ __export(list_changes_exports, {
 });
 import { join as join25 } from "path";
 import { existsSync as existsSync21, readdirSync as readdirSync13, readFileSync as readFileSync25 } from "fs";
-import yaml6 from "js-yaml";
+import yaml5 from "js-yaml";
 async function listChanges() {
   const cwd = process.cwd();
   const changesDir = join25(cwd, "specs", "changes");
@@ -10296,7 +10296,7 @@ async function listChanges() {
       if (existsSync21(tasksPath)) {
         try {
           const raw = readFileSync25(tasksPath, "utf8");
-          const data = yaml6.load(raw);
+          const data = yaml5.load(raw);
           if (data?.status)
             status = data.status;
           pending = (data?.tasks ?? []).filter((t) => t.status === "pending").length;
@@ -11104,7 +11104,6 @@ init_paths();
 import { join as join9, relative as relative3 } from "path";
 import { createHash as createHash4 } from "crypto";
 import { existsSync as existsSync8, readFileSync as readFileSync8, readdirSync as readdirSync5, writeFileSync as writeFileSync4 } from "fs";
-import yaml from "js-yaml";
 init_logger();
 init_context_scan();
 init_digest();
@@ -11173,6 +11172,20 @@ function parseDependsOn(raw) {
     return [];
   return raw.split(",").map((item) => item.trim()).filter(Boolean);
 }
+function applyScaffoldMetadata(tasksPath, changeId, dependencies) {
+  if (!existsSync8(tasksPath))
+    return;
+  let raw = readFileSync8(tasksPath, "utf8");
+  raw = raw.replace(/^change-id:\s*<change-id>\s*$/m, `change-id: ${changeId}`);
+  if (dependencies.length > 0) {
+    const dependsOn = [
+      "depends-on:",
+      ...dependencies.map((dep) => `  - ${JSON.stringify(dep)}`)
+    ].join("\n");
+    raw = raw.replace(/^depends-on:\s*\[\]\s*$/m, dependsOn);
+  }
+  writeFileSync4(tasksPath, raw, "utf8");
+}
 async function newChange(name, opts) {
   if (!SAFE_NAME.test(name)) {
     log.error(`Invalid change name: "${name}". Use letters, numbers, hyphens, or underscores (max 64 chars).`);
@@ -11220,15 +11233,10 @@ async function newChange(name, opts) {
     log.dim(tmpl);
     written += 1;
   }
+  const tasksPath = join9(changeDir, "tasks.yml");
+  applyScaffoldMetadata(tasksPath, name, dependencies);
   if (dependencies.length > 0) {
-    const tasksPath = join9(changeDir, "tasks.yml");
-    if (existsSync8(tasksPath)) {
-      const raw = readFileSync8(tasksPath, "utf8");
-      const data = yaml.load(raw) ?? {};
-      data["depends-on"] = dependencies;
-      writeFileSync4(tasksPath, yaml.dump(data, { lineWidth: -1, noRefs: true }), "utf8");
-      log.dim(`depends-on: ${dependencies.join(", ")}`);
-    }
+    log.dim(`depends-on: ${dependencies.join(", ")}`);
   }
   log.blank();
   log.ok(`${written} template(s) created in specs/changes/${name}`);
@@ -11330,7 +11338,7 @@ init_logger();
 import { existsSync as existsSync13, readFileSync as readFileSync16, readdirSync as readdirSync7 } from "fs";
 import { homedir as homedir3 } from "os";
 import { join as join16 } from "path";
-import yaml2 from "js-yaml";
+import yaml from "js-yaml";
 import picomatch2 from "picomatch";
 
 // src/schemas/agent-log.schema.ts
@@ -11571,7 +11579,7 @@ function loadContextPolicy(cwd) {
 function loadYamlFile(path) {
   try {
     const raw = readFileSync16(path, "utf8");
-    return { data: yaml2.load(raw, { schema: yaml2.JSON_SCHEMA }), parseError: null };
+    return { data: yaml.load(raw, { schema: yaml.JSON_SCHEMA }), parseError: null };
   } catch (err) {
     return { data: null, parseError: err.message };
   }

package/package.json

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