contract-driven-delivery 1.11.0 → 1.12.0

package/assets/cdd/context-policy.json

@@ -0,0 +1,25 @@
+{
+  "forbiddenPaths": [
+    ".claude/worktrees/**",
+    ".git/**",
+    "node_modules/**",
+    "dist/**",
+    "build/**",
+    "assets/**",
+    "specs/archive/**",
+    "specs/changes/*"
+  ],
+  "contextExpansion": {
+    "mode": "auto-safe",
+    "autoApprovePatterns": [
+      "src/**",
+      "tests/**",
+      "contracts/**",
+      "specs/changes/<current-change-id>/**"
+    ]
+  },
+  "audit": {
+    "requireFilesRead": true,
+    "unknownFilesRead": "warn-for-legacy-fail-for-new"
+  }
+}

package/assets/cdd/model-policy.json

@@ -0,0 +1,5 @@
+{
+  "provider": "claude",
+  "generated_at": null,
+  "roles": {}
+}

package/assets/contracts/api/api-contract.md

@@ -1,5 +1,8 @@
 ---
 contract: api
+summary: API behavior, compatibility rules, and endpoint contract requirements.
+owner: application-team
+surface: api
 schema-version: 0.1.0
 last-changed: 2026-04-27
 breaking-change-policy: deprecate-2-minors

package/assets/contracts/api/api-inventory.md

@@ -1,3 +1,10 @@
+---
+contract: api-inventory
+summary: Endpoint inventory categories and ownership map for non-standard API surfaces.
+owner: application-team
+surface: api
+---
+
 # API Inventory
 
 | method | path | category | owner | contract test | notes |

package/assets/contracts/api/error-format.md

@@ -1,3 +1,10 @@
+---
+contract: api-error-format
+summary: Standard error payload shape, safety rules, and reusable error code table.
+owner: application-team
+surface: api
+---
+
 # API Error Format
 
 ## Standard Error Shape

package/assets/contracts/business/business-rules.md

@@ -1,5 +1,8 @@
 ---
 contract: business
+summary: Business decision tables, rule inventory, and change policy for behavior updates.
+owner: application-team
+surface: domain-behavior
 schema-version: 0.1.0
 last-changed: 2026-04-27
 breaking-change-policy: deprecate-2-minors

package/assets/contracts/ci/ci-gate-contract.md

@@ -1,5 +1,8 @@
 ---
 contract: ci
+summary: CI gate inventory, artifact retention, and rollback requirements.
+owner: platform-team
+surface: delivery-pipeline
 schema-version: 0.1.0
 last-changed: 2026-04-27
 breaking-change-policy: deprecate-2-minors

package/assets/contracts/css/css-contract.md

@@ -1,5 +1,8 @@
 ---
 contract: css
+summary: UI token policy, component styling rules, and visual review constraints.
+owner: application-team
+surface: ui
 schema-version: 0.1.0
 last-changed: 2026-04-27
 breaking-change-policy: deprecate-2-minors

package/assets/contracts/css/design-tokens.md

@@ -1,3 +1,10 @@
+---
+contract: design-tokens
+summary: Canonical design token inventory for colors, spacing, typography, and layering.
+owner: design-system
+surface: ui
+---
+
 # Design Tokens
 
 ## Colors

package/assets/contracts/data/data-shape-contract.md

@@ -1,5 +1,8 @@
 ---
 contract: data
+summary: Data schema, invalid-data handling, and row-level compatibility rules.
+owner: application-team
+surface: data
 schema-version: 0.1.0
 last-changed: 2026-04-27
 breaking-change-policy: deprecate-2-minors

package/assets/contracts/env/env-contract.md

@@ -1,5 +1,8 @@
 ---
 contract: env
+summary: Environment variable inventory, secret handling, and deployment sync policy.
+owner: platform-team
+surface: runtime-config
 schema-version: 0.1.0
 last-changed: 2026-04-27
 breaking-change-policy: deprecate-2-minors

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

@@ -10,10 +10,18 @@ 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 `contracts/` or `CLAUDE.md`
+3. Durable learnings have been promoted to hot sources: `contracts/`, `CLAUDE.md`, or `CODEX.md`
 
 This skill drives steps 2–3 and physically moves the change to `specs/archive/`.
 
+## Hot / Warm / Cold Data Rules
+
+- Hot data: `contracts/`, source files, tests, CI config, `CLAUDE.md`, `CODEX.md`.
+- Warm data: the active `specs/changes/<change-id>/` directory while the change is open.
+- Cold data: `specs/archive/` after close.
+
+Cold data is historical evidence, not current requirements. Do not promote claims from old specs or archive prose unless they are backed by agent-log evidence, QA evidence, changed contracts, changed tests, or passing gates from this change.
+
 ## Input
 
 The skill argument is the change-id (e.g., `add-jwt-auth`).
@@ -58,7 +66,14 @@ If `7.2` is `[ ]`, proceed to Step 2.5. If already `[x]` or `[-]`, skip Steps 2.
 
 ## Step 2.5: Create archive.md
 
-Read `specs/changes/<change-id>/agent-log/` (all log files) and `specs/changes/<change-id>/qa-report.md` (if exists).
+Read only active evidence for this change:
+- `specs/changes/<change-id>/agent-log/` (all log files)
+- `specs/changes/<change-id>/qa-report.md` (if exists)
+- `specs/changes/<change-id>/ci-gates.md`
+- `specs/changes/<change-id>/context-manifest.md`
+- `specs/changes/<change-id>/tasks.md`
+
+Do not read `specs/archive/` while closing a change. Historical archives are cold data and must not be used as current requirements.
 
 Synthesize a `specs/changes/<change-id>/archive.md` file with:
 - **Change Summary**: 1 paragraph what was changed and why
@@ -69,24 +84,33 @@ Synthesize a `specs/changes/<change-id>/archive.md` file with:
 - **Production Reality Findings**: any surprises or deviations from the plan (from qa-reviewer agent-log)
 - **Lessons Promoted to Standards**: (leave blank — to be filled in Step 3)
 - **Follow-up Work**: any known issues deferred
+- **Cold Data Warning**: "This archive is historical evidence. Current requirements live in contracts/ and active project guidance."
 
-This file is the source for Step 3's learning promotion.
+This file records the close-out evidence, but Step 3 promotion must still be evidence-gated. Archive prose alone is not enough to change hot data.
 
 ---
 
 ## Step 3: Promote learnings (task 7.2)
 
-Read `specs/changes/<change-id>/archive.md` section `## Lessons Promoted to Standards`.
+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:
+- **promote-to-contract**: stable product/system behavior, API/data/env/business/CI rule, compatibility rule, or testable invariant.
+- **promote-to-guidance**: durable workflow guidance for future agents, provider-specific operating instructions, or project-specific agent constraints. Target `CLAUDE.md` and/or `CODEX.md`.
+- **do-not-promote**: one-off implementation detail, abandoned approach, temporary workaround, historical rationale, or anything contradicted by current contracts.
 
 If there are lessons to promote, invoke `contract-reviewer` with:
 - The archive.md lessons section
-- Instruction: "Review these lessons and propose specific additions to the relevant contract files. For each lesson, output: target file, target section, proposed text (≤ 5 lines), schema-version bump required (yes/no)."
+- Supporting evidence from agent-log / QA / changed contracts / changed tests
+- Instruction: "Review these lessons and propose specific additions only for evidence-backed durable rules. For each lesson, output: classification, target file, target section, proposed text (≤ 5 lines), evidence path, schema-version bump required (yes/no). Reject any cold-data-only or one-off lesson."
 
 After contract-reviewer responds:
-1. Apply each proposed addition to the contract file (YOU write)
-2. Run `cdd-kit validate --contracts` to confirm format is preserved
-3. Fill in `## Lessons Promoted to Standards` in archive.md with what was promoted
-4. Tick `7.2` in tasks.md
+1. Apply each approved contract addition to the contract file (YOU write)
+2. Apply each approved guidance addition to `CLAUDE.md` and/or `CODEX.md` only if it is provider/project guidance, not product behavior
+3. Run `cdd-kit validate --contracts` to confirm contract format is preserved
+4. Run `cdd-kit context-scan` so future classifiers see updated hot context indexes
+5. Fill in `## Lessons Promoted to Standards` in archive.md with what was promoted, where, and evidence path
+6. Tick `7.2` in tasks.md
 
 If there are no lessons to promote, mark `[-]` for 7.2 with rationale.
 
@@ -108,7 +132,7 @@ If successful, tick `7.1` in tasks.md (the file is now in specs/archive/, update
 
 Change ID: <change-id>
 Archived to: specs/archive/<year>/<change-id>/
-Learnings promoted: <list what was added to contracts/CLAUDE.md, or "none">
+Learnings promoted: <list what was added to contracts/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.
@@ -120,4 +144,7 @@ Token cost of future sessions reduced by ~<N> files.
 
 - NEVER archive before gate passes (unless user explicitly confirms abandoned)
 - NEVER skip Step 3 — lessons rot if not promoted
+- NEVER treat `specs/archive/` as hot requirements
+- NEVER promote a lesson without an evidence path from this change
+- Product behavior belongs in `contracts/`; agent workflow guidance belongs in `CLAUDE.md` and/or `CODEX.md`
 - The archive command is irreversible without git — remind user to commit after archiving

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

@@ -72,7 +72,7 @@ If the classifier marks an artifact as `no` or leaves it blank, **do not create
 
 The 5 always-required artifacts are: `change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.md`.
 
-## Step 1: Generate change-id and scaffold
+## Step 1: Generate change-id, scaffold, and scan context
 
 Derive a `change-id` from the description:
 - kebab-case, max 5 words
@@ -80,9 +80,28 @@ Derive a `change-id` from the description:
 
 Check that `specs/changes/<change-id>/` does not already exist. If it does, append `-2` (or next available suffix).
 
-**Create all scaffold files using Write (do NOT run a Python script; do NOT use Edit on pre-existing files):**
+Create the scaffold with the CLI so every provider gets the same templates:
 
-Create `specs/changes/<change-id>/change-request.md` with the user's description filled in:
+```bash
+cdd-kit new <change-id>
+```
+
+Then build deterministic context indexes before invoking any classifier:
+
+```bash
+cdd-kit context-scan
+```
+
+Verify these files exist:
+- `specs/changes/<change-id>/context-manifest.md`
+- `specs/context/project-map.md`
+- `specs/context/contracts-index.md`
+
+Do not use broad search or ad hoc reads to classify the change before `context-scan` has completed.
+
+The generated scaffold contains the artifacts below. Fill `change-request.md` with the user's request before invoking the classifier.
+
+Update `specs/changes/<change-id>/change-request.md` with the user's description filled in:
 ```
 # Change Request: <change-id>
 
@@ -104,7 +123,7 @@ Create `specs/changes/<change-id>/change-request.md` with the user's description
 as soon as possible
 ```
 
-Create `specs/changes/<change-id>/change-classification.md` with blank template:
+`specs/changes/<change-id>/change-classification.md` starts from this blank template:
 ```
 # Change Classification
 
@@ -163,7 +182,7 @@ Always required: change-request.md, change-classification.md, test-plan.md, ci-g
 ## Assumptions / Clarifications
 ```
 
-Create `specs/changes/<change-id>/test-plan.md` with blank template:
+`specs/changes/<change-id>/test-plan.md` starts from this blank template:
 ```
 # Test Plan: <change-id>
 
@@ -182,7 +201,7 @@ Create `specs/changes/<change-id>/test-plan.md` with blank template:
 (Keep under 10 lines. Implementation detail belongs in the test files themselves.)
 ```
 
-Create `specs/changes/<change-id>/ci-gates.md` with blank template:
+`specs/changes/<change-id>/ci-gates.md` starts from this blank template:
 ```
 # CI Gates: <change-id>
 
@@ -195,11 +214,13 @@ Create `specs/changes/<change-id>/ci-gates.md` with blank template:
 ## Promotion Policy
 ```
 
-Create `specs/changes/<change-id>/tasks.md` with ALL checkboxes unchecked:
+`specs/changes/<change-id>/tasks.md` starts with ALL checkboxes unchecked:
 ```
 ---
 change-id: <change-id>
 status: in-progress
+context-governance: v1
+depends-on: []
 ---
 
 <!-- [x]=done [-]=N/A [ ]=pending -->
@@ -255,16 +276,28 @@ status: in-progress
 
 Invoke `change-classifier` agent with:
 - The user's change description
-- The project profile at `specs/project-profile.md` (if it exists)
-- The existing contracts in `contracts/` (if any)
+- `specs/changes/<change-id>/change-request.md`
+- `specs/changes/<change-id>/context-manifest.md`
+- `specs/context/project-map.md`
+- `specs/context/contracts-index.md`
+
+Do not authorize the classifier to read `contracts/`, `src/`, `tests/`, or broad repository search during initial classification. It must use the context indexes to propose candidate paths.
+
+The classifier must include a `## Context Manifest Draft` section with:
+- affected surfaces
+- allowed paths for each required agent work packet
+- required contracts
+- required tests
+- any context expansion requests that must be approved before implementation
 
 **change-classifier is read-only** — it will return its output as text. After it responds:
 
 1. **YOU write** `specs/changes/<change-id>/change-classification.md` — replace the blank template with the classifier's classification output.
 2. **YOU write** `specs/changes/<change-id>/agent-log/change-classifier.md` — copy the Agent Log block from the classifier's response.
-3. **YOU tick** `tasks.md` item `1.1`.
+3. **YOU update** `specs/changes/<change-id>/context-manifest.md` from the classifier's `## Context Manifest Draft`.
+4. **YOU tick** `tasks.md` item `1.1`.
 
-Wait until these three writes are done before continuing.
+Wait until these four writes are done before continuing.
 
 **After writing change-classification.md**: read the classifier's `## Tasks Not Applicable` list. For each listed task ID (e.g., `2.2`, `4.2`), update `tasks.md` to change that item from `[ ]` to `[-]`. Do this before invoking any other agent.
 

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

@@ -37,7 +37,15 @@ If there are many mid-flight changes, suggest `cdd-kit migrate --all` instead.
 
 ## Step 1: Read current state
 
-Read `specs/changes/<change-id>/tasks.md`:
+Read only these state files first:
+- `specs/changes/<change-id>/tasks.md`
+- `specs/changes/<change-id>/context-manifest.md` if present
+- `specs/changes/<change-id>/agent-log/*.md`
+- `specs/changes/<change-id>/change-classification.md`
+
+Do not run broad repository search during resume. Do not read `src/`, `tests/`, or `contracts/` unless the current `context-manifest.md` authorizes that path or an approved expansion lists it.
+
+From `tasks.md`:
 - Identify all `[x]` (done) items
 - Identify all `[-]` (N/A) items  
 - Identify all `[ ]` (pending) items
@@ -46,6 +54,12 @@ Read `specs/changes/<change-id>/agent-log/` to list which agents have already ru
 
 Read `specs/changes/<change-id>/change-classification.md` to recall the tier and required agents.
 
+Read `specs/changes/<change-id>/context-manifest.md`:
+- Identify allowed paths and approved expansions.
+- Identify pending Context Expansion Requests.
+- If any request has `status: pending`, stop before invoking agents. Report the request id, requested paths, and reason; ask the user to approve, reject, or narrow it.
+- If `context-manifest.md` is missing on a legacy change, run `cdd-kit migrate <change-id>` before continuing. For context-governed changes, missing manifest is blocking.
+
 ---
 
 ## Step 2: Report state and ask to continue
@@ -60,6 +74,8 @@ Status: <in-progress | gate-blocked>
 
 Completed agents: <list from agent-log/>
 Pending tasks: <list of [ ] items>
+Pending context expansions: <none | list request ids and paths>
+Allowed context: <short summary from context-manifest.md>
 
 Next agent to run: <agent-name> (based on tier flow and what's missing)
 ```
@@ -72,7 +88,17 @@ Ask the user: "Continue from <next-agent>? (yes/no)"
 
 If user confirms, resume from the next agent in the Tier sequence (refer to `/cdd-new` Step 3 for the agent order). 
 
-**Critical**: Inject `CURRENT_CHANGE_ID: <change-id>` at the start of every agent prompt. Do NOT re-run agents that already have a `status: complete` agent-log.
+**Critical**: Inject this block at the start of every agent prompt:
+
+```
+CURRENT_CHANGE_ID: <change-id>
+Change directory: specs/changes/<change-id>/
+Context manifest: specs/changes/<change-id>/context-manifest.md
+Read only paths allowed by the context manifest and approved expansions.
+If more context is needed, stop and output a Context Expansion Request instead of reading outside the manifest.
+```
+
+Do NOT re-run agents that already have a `status: complete` agent-log.
 
 Continue until all required agents are done, then run `cdd-kit gate <change-id>`.
 
@@ -82,5 +108,7 @@ Continue until all required agents are done, then run `cdd-kit gate <change-id>`
 
 - Never re-run an agent that already has `status: complete` in its agent-log
 - Never start from Step 1 of `/cdd-new` — only resume from the next pending agent
+- Never use broad search to reconstruct state; resume from `tasks.md`, `context-manifest.md`, and `agent-log/`
+- Never continue past pending Context Expansion Requests
 - If tasks.md has `status: abandoned`, report to user and stop
 - If tasks.md has `status: gate-blocked`, go directly to gate retry (max 3)

package/assets/specs-templates/context-manifest.md

@@ -0,0 +1,49 @@
+# Context Manifest
+
+This manifest defines the approved context boundaries for agents working on this change.
+
+## Affected Surfaces
+-
+
+## Allowed Paths
+- specs/changes/<change-id>/
+
+## Forbidden Paths
+- .claude/worktrees/**
+- .git/**
+- node_modules/**
+- dist/**
+- build/**
+- assets/**
+- specs/archive/**
+- specs/changes/* except specs/changes/<change-id>/
+
+## Required Contracts
+-
+
+## Required Tests
+-
+
+## Agent Work Packets
+
+### change-classifier
+- allowed:
+  - specs/changes/<change-id>/
+  - specs/context/project-map.md
+  - specs/context/contracts-index.md
+
+## Context Expansion Requests
+
+<!--
+Agents must request context expansion instead of reading outside their work packet.
+Use this format only for real requests:
+
+- request-id: CER-001
+  requested_paths:
+    - src/example.ts
+  reason: why this file is required
+  status: pending
+-->
+
+## Approved Expansions
+-

package/assets/specs-templates/tasks.md

@@ -1,6 +1,8 @@
 ---
 change-id: <change-id>
 status: in-progress
+context-governance: v1
+depends-on: []
 ---
 
 <!-- [x]=done [-]=N/A [ ]=pending -->