contract-driven-delivery 2.0.0 → 2.0.2

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## [2.0.2] - 2026-04-30
+
+### Added
+
+- `npm postinstall` hook: after `npm install -g` or `npm update -g`, skills and
+  agents in `~/.claude/` are automatically synced to the newly installed version.
+  The sync is a no-op when `cdd-kit init` has never been run (safe for CI and
+  local dev installs of the package itself). A backup of any locally modified
+  files is created in `~/.claude/.cdd-kit-backup/<timestamp>/` before overwriting,
+  matching the existing `cdd-kit update --yes` behaviour.
+- `cdd-kit update --postinstall` flag (internal): quiet mode that implies
+  `--yes`, locks provider to `claude`, and silently exits when the skill
+  directory is absent. Not intended for direct user invocation.
+
+### Migration note
+
+The first `npm update -g contract-driven-delivery` that brings in this version
+will **not** auto-sync (the postinstall hook did not exist in the previously
+installed version). Run `cdd-kit update --yes` once after this upgrade; all
+subsequent upgrades will auto-sync.
+
+## [2.0.1] - 2026-04-30
+
+### Fixed
+
+- Clarified the agent ownership model in the public docs so read-only reviewers
+  and write-capable implementation agents have explicit, non-conflicting file
+  ownership rules.
+- Aligned bundled prompts so read-only agents emit an `Agent Log` YAML block
+  for main Claude to persist, while write-capable agents continue writing their
+  own artifacts and `agent-log/*.yml` files.
+- Synchronized package version metadata for the post-`2.0.0` publish path.
+
 ## [2.0.0] - 2026-04-30
 
 ### BREAKING: structured YAML for tasks and agent-log

package/README.md

@@ -99,6 +99,19 @@ 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
 
+### Agent Ownership Model
+
+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`.
+
+This split is deliberate:
+
+- Review and audit agents stay read-only so they do not silently change the thing they are supposed to assess.
+- Implementation and planning agents write directly so large artifacts and code edits do not have to be relayed back through the main orchestrator, which reduces token waste and preserves clearer ownership.
+- `tasks.yml` remains owned by main Claude so task state changes stay centralized even when multiple agents contribute files.
+
 **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

package/assets/CODEX.template.md

@@ -18,12 +18,12 @@ Read `specs/changes/<change-id>/context-manifest.md` before using file-reading o
 - Read only paths allowed by the manifest or approved expansions.
 - 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/*.md` under `- files-read:`.
+- Record every file read through tools in the relevant `agent-log/*.yml` under `files-read:`.
 
-Required `agent-log/*.md` format:
+Required `agent-log/*.yml` format:
 
-```md
-- files-read:
+```yaml
+files-read:
   - contracts/api/api-contract.md
   - src/server/routes/users.ts
 ```

package/assets/agents/change-classifier.md

@@ -225,7 +225,8 @@ Note: `archive.md` is created during change close-out, not at classification tim
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to
+After completing your task, end your response with an `Agent Log` YAML block
+for main Claude to write 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.

package/assets/agents/contract-reviewer.md

@@ -63,7 +63,8 @@ approved / changes-required
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to
+After completing your task, end your response with an `Agent Log` YAML block
+for main Claude to write 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.

package/assets/agents/dependency-security-reviewer.md

@@ -64,7 +64,8 @@ approved / changes-required / blocked
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to
+After completing your task, end your response with an `Agent Log` YAML block
+for main Claude to write 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.
@@ -74,4 +75,3 @@ field rules, and gate-enforcement behavior are defined once in
 - `cve-findings`: count + severity buckets
 - `license-issues`: list or "none"
 - `lockfile-changes`: list of files
-

package/assets/agents/qa-reviewer.md

@@ -75,7 +75,8 @@ approved / blocked / approved-with-risk
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to
+After completing your task, end your response with an `Agent Log` YAML block
+for main Claude to write 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.

package/assets/agents/repo-context-scanner.md

@@ -84,7 +84,8 @@ frontend / backend / fullstack / monorepo / library / tool
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to
+After completing your task, end your response with an `Agent Log` YAML block
+for main Claude to write 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.
@@ -93,4 +94,3 @@ field rules, and gate-enforcement behavior are defined once in
 - `profile-path`: `project-profile.generated.md`
 - `stack-detected`: from cdd-kit detect-stack
 - `surfaces-flagged`: list of missing standardization surfaces
-

package/assets/agents/spec-drift-auditor.md

@@ -52,7 +52,8 @@ By default, do NOT read `specs/changes/` history. Only read historical change re
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to
+After completing your task, end your response with an `Agent Log` YAML block
+for main Claude to write 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.
@@ -62,4 +63,3 @@ field rules, and gate-enforcement behavior are defined once in
 - `drift-items`: count + severity
 - `drift-summary-path`: `specs/audits/<YYYY-MM-DD>-drift-audit.md`
 - `next-audit-due`: ISO date
-

package/assets/agents/ui-ux-reviewer.md

@@ -51,7 +51,8 @@ approved / changes-required
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to
+After completing your task, end your response with an `Agent Log` YAML block
+for main Claude to write 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.
@@ -61,4 +62,3 @@ field rules, and gate-enforcement behavior are defined once in
 - `state-coverage`: list of `<screen>: empty/loading/error/success` matrix
 - `copy-issues`: count + severity
 - `accessibility-findings`: count + severity
-

package/assets/agents/visual-reviewer.md

@@ -53,7 +53,8 @@ approved / changes-required
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to
+After completing your task, end your response with an `Agent Log` YAML block
+for main Claude to write 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.
@@ -63,4 +64,3 @@ field rules, and gate-enforcement behavior are defined once in
 - `diff-percentage`: per-screen
 - `state-coverage`: matrix
 - `tokens-violated`: list of CSS contract violations or "none"
-

package/bin/postinstall.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+try {
+  const cliPath = join(__dirname, '..', 'dist', 'cli', 'index.js');
+  if (!existsSync(cliPath)) process.exit(0);
+
+  spawnSync(process.execPath, [cliPath, 'update', '--postinstall'], {
+    stdio: 'inherit',
+    timeout: 30_000,
+  });
+  process.exit(0);
+} catch {
+  process.exit(0);
+}

package/dist/cli/index.js

@@ -11673,7 +11673,16 @@ function backupDir(dir, backupDest) {
   walk(dir, backupDest);
 }
 async function update(opts) {
-  log.blank();
+  if (opts.postinstall) {
+    if (!existsSync5(join6(SKILLS_HOME, "contract-driven-delivery"))) {
+      return;
+    }
+    opts.yes = true;
+    opts.provider = "claude";
+  }
+  const quiet = !!opts.postinstall;
+  if (!quiet)
+    log.blank();
   const cwd = process.cwd();
   const requestedProvider = opts.provider ?? "auto";
   if (!validateProviderOption(requestedProvider)) {
@@ -11689,28 +11698,32 @@ async function update(opts) {
   const toAdd = toWrite.filter((e) => e.action === "add");
   const toOver = toWrite.filter((e) => e.action === "overwrite");
   const toSkip = [...agentDiff, ...skillDiff].filter((e) => e.action === "skip");
-  log.info(`Provider: ${provider}`);
-  if (updateClaudeAssets) {
-    log.info(`Dry-run diff \u2014 agents: ${AGENTS_HOME}`);
-    log.info(`Dry-run diff \u2014 skill:  ${skillDest}`);
-  } else {
-    log.info("Codex provider has no global cdd-kit assets to update.");
-    log.info("Project files are preserved; run cdd-kit init --local-only --provider codex to add missing local guidance.");
+  if (!quiet) {
+    log.info(`Provider: ${provider}`);
+    if (updateClaudeAssets) {
+      log.info(`Dry-run diff \u2014 agents: ${AGENTS_HOME}`);
+      log.info(`Dry-run diff \u2014 skill:  ${skillDest}`);
+    } else {
+      log.info("Codex provider has no global cdd-kit assets to update.");
+      log.info("Project files are preserved; run cdd-kit init --local-only --provider codex to add missing local guidance.");
+    }
+    log.blank();
+    if (toAdd.length)
+      log.info(`  + ${toAdd.length} file(s) would be added`);
+    if (toOver.length)
+      log.warn(`  ~ ${toOver.length} file(s) would be overwritten (user edits lost without backup)`);
+    if (toSkip.length)
+      log.dim(`    ${toSkip.length} file(s) unchanged (skipped)`);
   }
-  log.blank();
-  if (toAdd.length)
-    log.info(`  + ${toAdd.length} file(s) would be added`);
-  if (toOver.length)
-    log.warn(`  ~ ${toOver.length} file(s) would be overwritten (user edits lost without backup)`);
-  if (toSkip.length)
-    log.dim(`    ${toSkip.length} file(s) unchanged (skipped)`);
   if (toWrite.length === 0) {
-    log.blank();
-    log.ok("Already up to date \u2014 nothing to write.");
-    log.blank();
+    if (!quiet) {
+      log.blank();
+      log.ok("Already up to date \u2014 nothing to write.");
+      log.blank();
+    }
     return;
   }
-  if (!opts.yes) {
+  if (!quiet && !opts.yes) {
     log.blank();
     log.info("Run with --yes to apply changes. Example:");
     log.dim("  cdd-kit update --yes");
@@ -11719,25 +11732,41 @@ async function update(opts) {
   }
   const timestamp2 = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
   const backupRoot = join6(homedir2(), ".claude", ".cdd-kit-backup", timestamp2);
-  log.blank();
-  log.info(`Backing up to ${backupRoot} \u2026`);
+  if (!quiet) {
+    log.blank();
+    log.info(`Backing up to ${backupRoot} \u2026`);
+  }
   backupDir(AGENTS_HOME, join6(backupRoot, "agents"));
   backupDir(skillDest, join6(backupRoot, "skill"));
-  log.ok(`Backup complete: ${backupRoot}`);
-  log.blank();
+  if (!quiet)
+    log.ok(`Backup complete: ${backupRoot}`);
+  if (!quiet)
+    log.blank();
+  let totalSynced = 0;
   if (updateClaudeAssets) {
-    log.info(`Updating agents \u2192 ${AGENTS_HOME}`);
+    if (!quiet)
+      log.info(`Updating agents \u2192 ${AGENTS_HOME}`);
     const agentCount = applyDir(agentDiff);
-    log.ok(`${agentCount} agent file(s) updated.`);
-    log.info(`Updating skill  \u2192 ${skillDest}`);
+    if (!quiet)
+      log.ok(`${agentCount} agent file(s) updated.`);
+    totalSynced += agentCount;
+    if (!quiet)
+      log.info(`Updating skill  \u2192 ${skillDest}`);
     const skillCount = applyDir(skillDiff);
-    log.ok(`${skillCount} skill file(s) updated.`);
+    if (!quiet)
+      log.ok(`${skillCount} skill file(s) updated.`);
+    totalSynced += skillCount;
+  }
+  if (quiet) {
+    if (totalSynced > 0)
+      log.ok(`cdd-kit: synced ${totalSynced} file(s) to ~/.claude/`);
+  } else {
+    log.blank();
+    log.info("Project files (contracts/, specs/, tests/, ci/) were not changed.");
+    log.ok("Update complete.");
+    log.info(`Backup saved to: ${backupRoot}`);
+    log.blank();
   }
-  log.blank();
-  log.info("Project files (contracts/, specs/, tests/, ci/) were not changed.");
-  log.ok("Update complete.");
-  log.info(`Backup saved to: ${backupRoot}`);
-  log.blank();
 }
 
 // src/commands/new-change.ts
@@ -12657,7 +12686,7 @@ program.command("init").description(
     provider: opts.provider
   })
 );
-program.command("update").description("Update provider assets for the current project (does not overwrite project guidance files)").option("--yes", "Apply changes (default is dry-run)", false).option("--provider <provider>", "Provider adapter to update: auto, claude, codex, or both", "auto").action((opts) => update({ yes: opts.yes, provider: opts.provider }));
+program.command("update").description("Update provider assets for the current project (does not overwrite project guidance files)").option("--yes", "Apply changes (default is dry-run)", false).option("--provider <provider>", "Provider adapter to update: auto, claude, codex, or both", "auto").option("--postinstall", "Internal: invoked by npm postinstall; no-op if cdd has not been init-ed", false).action((opts) => update({ yes: opts.yes, provider: opts.provider, postinstall: opts.postinstall }));
 program.command("doctor").description("Inspect cdd-kit repo health, provider guidance, and context index freshness").option("--strict", "Treat warnings as errors", false).option("--json", "Print a machine-readable health report", false).option("--provider <provider>", "Provider adapter to inspect: auto, claude, codex, or both", "auto").option("--fix", "Auto-resolve safe warnings (stale context indexes, missing role bindings)", false).action(async (opts) => {
   const { doctor: doctor2 } = await Promise.resolve().then(() => (init_doctor(), doctor_exports));
   await doctor2({ strict: opts.strict, json: opts.json, provider: opts.provider, fix: opts.fix });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contract-driven-delivery",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "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",
@@ -40,7 +40,8 @@
     "build": "node build.js",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "node build.js && vitest run"
+    "prepublishOnly": "node build.js && vitest run",
+    "postinstall": "node bin/postinstall.js"
   },
   "engines": {
     "node": ">=18.0.0"