contract-driven-delivery 1.9.0 → 1.11.0

package/assets/CLAUDE.template.md

@@ -1,215 +1,42 @@
 # CLAUDE.md
 
-This repository follows the Contract-Driven Delivery workflow.
-
-## First response rule
-
-Before implementing any request, classify the change type and determine which contracts, tests, CI/CD gates, and review agents are required.
-
-Do not start production code changes until the required artifacts are created or explicitly judged unnecessary with rationale.
-
-## Change types
-
-Classify every request as one or more of:
-
-- `new-feature`
-- `feature-enhancement`
-- `business-logic-change`
-- `bug-fix`
-- `regression-fix`
-- `ui-only-change`
-- `api-only-change`
-- `env-change`
-- `data-contract-change`
-- `performance-change`
-- `refactor`
-- `ci-cd-change`
-- `test-hardening-change`
-
-## Stack-aware CI
-
-`cdd-kit init` auto-detects the project tech stack and patches the fast-gate step in `ci/github-actions/contract-driven-gates.yml` with stack-specific commands. Supported stacks:
-
-- **Python**: conda (default/preferred), poetry, uv, pip
-- **JavaScript**: pnpm, bun, yarn, npm
-- **Go**: go
-- **Rust**: rust
-
-For Conda projects, the generated CI uses `conda-incubator/setup-miniconda@v3` with `shell: bash -el {0}` (required for Conda env activation in GitHub Actions). If `cdd-kit init` could not detect a stack, fill in the placeholder step manually.
-
-Run `cdd-kit detect-stack` at any time to see what the detector found.
-
-## Required context discovery
-
-Inspect the repository before planning:
-
-- package manager and lockfiles (environment.yml for Conda, pyproject.toml for poetry/uv, etc.)
-- frontend framework and build tool
-- backend framework and app entrypoints
-- routing/controllers/API layers
-- API contract and inventory files
-- CSS/design token/component contract files
-- env files, `.env.example`, deployment configs, secret handling
-- test frameworks and existing test folders
-- CI/CD workflows and required checks
-- data/report schemas and column contracts
-- worker, queue, cache, database, storage, and external service boundaries
-
-Write or update a project profile when working in an unfamiliar repo.
-
-## Required artifact path
-
-For a meaningful change, use or create:
-
-```text
-specs/changes/<change-id>/
-├── change-request.md
-├── change-classification.md
-├── current-behavior.md
-├── proposal.md
-├── spec.md
-├── design.md
-├── contracts.md
-├── test-plan.md
-├── ci-gates.md
-├── tasks.md
-├── qa-report.md
-├── regression-report.md
-└── archive.md
-```
-
-## Contract versioning
-
-Contracts use semver via frontmatter; bump schema-version + add CHANGELOG entry on every contract change. Each contract file contains a YAML frontmatter block with `contract`, `schema-version`, `last-changed`, and `breaking-change-policy`. All changes at 1.0+ must be recorded in `contracts/CHANGELOG.md` using the format `## [<type> <version>] — <date>`. Major version bumps additionally require a `### Removed` or `### Changed (breaking)` section. The `validate_contract_versions.py` script enforces these rules automatically in CI and via `cdd-kit validate --versions`.
-
-## Contract rules
-
-### API
-
-Any API behavior change must update API contract, endpoint inventory, response/error format expectations, frontend service/types, and contract tests.
-
-### CSS/UI
-
-Any visual or component behavior change must update CSS/UI contract, token usage, component states, responsive behavior, and visual review evidence.
-
-### Env
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-Any new or changed environment variable must update env contract, `.env.example`, validation rules, runtime scope, deployment documentation, and secret policy.
+## Project overview
 
-### Data/report shape
+<TODO: one-sentence description of what this repo does and who uses it>
 
-Any report, dashboard, export, import, or table-like data change must define required columns, types, nullability, coercion/rejection rules, row limits, empty-state behavior, and malformed-data behavior.
+## Dev commands
 
-### Business logic
+<TODO: fill in install / dev / test / lint / build commands for this project>
 
-Any business rule change must include current rule, new rule, decision table, examples, edge cases, backward compatibility, migration/data impact, and regression tests.
+## Architecture
 
-### CI/CD
+<TODO: describe main modules, service boundaries, and entry points>
 
-Every change must define the required gates. CI/CD is part of delivery, not an afterthought.
+---
 
-## Testing rules
-
-Use the lowest necessary test level, but do not skip production-reality coverage when risk requires it.
-
-Required test families:
-
-- unit tests
-- contract tests
-- integration tests
-- E2E tests
-- visual regression or visual review evidence
-- data-boundary tests
-- resilience tests
-- fuzz or monkey-operation tests
-- stress tests for concurrency/load-sensitive paths
-- soak tests for long-running or auto-refresh/report systems
-
-For bug fixes, write or identify a failing test before fixing whenever feasible.
-
-For resilience or fault tests, include a mutation check where practical: remove or bypass the intended handler and confirm the test fails.
-
-## CI/CD gate policy
-
-Use these tiers:
-
-- Tier 0: local fast gate
-- Tier 1: PR required gate
-- Tier 2: PR informational gate
-- Tier 3: nightly real-infra gate
-- Tier 4: weekly soak/stress gate
-- Tier 5: manual production-like dispatch gate
-
-Long-running or flaky gates may start as informational, but must have promotion criteria and owners.
-
-## Visual review policy
-
-Frontend changes that alter UI output require:
-
-- affected screen list
-- viewport list
-- state list: default, loading, empty, error, disabled, long text, no permission
-- screenshot or video evidence where possible
-- CSS contract check
-- accessibility check for focus, keyboard, labels, and contrast
-
-## Orchestration enforcement
-
-Every change in `specs/changes/<change-id>/` must pass `cdd-kit gate <change-id>` before the implementation is committed. The gate enforces:
-
-1. All 5 required artifacts exist (`change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.md`)
-2. Each artifact has more than 100 meaningful characters (not a stub template)
-3. `change-classification.md` contains a tier marker (`Tier 0`–`Tier 5`) or a risk label (`low`, `medium`, `high`, `critical`)
-4. Agent-log files in `specs/changes/<change-id>/agent-log/` are valid (if present)
-5. All contract validators pass (`cdd-kit validate`)
-
-## Agent-log rules
-
-Each agent writes a machine-verifiable log to `specs/changes/<change-id>/agent-log/<agent-name>.md` after completing its task. The gate validates these logs automatically.
-
-Required log structure:
-
-```
-# <Agent Display Name> Log
-- change-id: <id>
-- timestamp: <ISO 8601>
-- status: complete | needs-review | blocked
-- artifacts:
-  - <evidence-type>: <concrete pointer>
-- next-action: <one line, or "none">
-```
-
-Rules enforced by `cdd-kit gate`:
-- The `status:` line must be present and set to `complete`, `needs-review`, or `blocked`.
-- When `status: blocked`, the `next-action:` line must be a concrete action of at least 10 characters (not "none").
-- Missing or invalid logs cause the gate to fail with a descriptive error.
-- A missing `agent-log/` directory is acceptable (gate passes when no agents have logged yet).
-
-Run `cdd-kit install-hooks` once in each repository to install a pre-commit hook that enforces the gate automatically on every commit touching `specs/changes/`. This prevents the workflow from being silently skipped.
-
-```bash
-cdd-kit gate add-user-auth      # manual check
-cdd-kit install-hooks           # install automatic pre-commit enforcement
-```
-
-## Forbidden practices
-
-- Do not implement before classifying the change.
-- Do not introduce undocumented API endpoints.
-- Do not change response shape without contract and client updates.
-- Do not add undocumented env vars.
-- Do not expose secrets through frontend-public env vars such as `VITE_`, `NEXT_PUBLIC_`, or `PUBLIC_`.
-- Do not hard-code visual tokens when a token system exists.
-- Do not bypass CI/CD gate planning.
-- Do not mark tasks complete without implementation evidence.
-- Do not hide production-reality failures by converting tests into superficial assertions.
-
-## Done criteria
-
-A change is complete only when:
+This repository follows the Contract-Driven Delivery workflow.
 
-- specs and contracts reflect the final behavior
-- test coverage maps to acceptance criteria
-- CI/CD gates pass or are explicitly documented as informational with promotion path
-- QA report records commands, evidence, and known residual risks
-- archive captures reusable learnings and standard updates
+- `contracts/` is the single source of truth for what the system should do.
+- `tests/` proves the contracts hold.
+- `specs/changes/<id>/` records why decisions were made (passive archive — read only when investigating history).
+- To start any non-trivial change, use `/cdd-new <description>` in Claude Code.
+
+## CDD Kit Commands
+
+| command | when to use |
+|---|---|
+| `/cdd-new <description>` | start a new tracked change (scaffolds all artifacts, runs full agent flow) |
+| `/cdd-resume <id>` | continue an in-progress change after a session break |
+| `/cdd-close <id>` | close a completed change: promote learnings, archive |
+| `cdd-kit list` | show all active changes and their status |
+| `cdd-kit gate <id>` | verify a change is gate-ready (run before PR) |
+| `cdd-kit gate <id> --strict` | full gate with pending-task enforcement (pre-commit default) |
+| `cdd-kit archive <id>` | physically move a completed change to `specs/archive/<year>/` |
+| `cdd-kit abandon <id> --reason <text>` | mark a change as abandoned; preserves directory for git history |
+| `cdd-kit migrate <id> \| --all` | upgrade pre-v1.11 change directories to new format (frontmatter + tier format) |
+| `cdd-kit validate` | run all contract validators |
+| `cdd-kit detect-stack` | detect the project tech stack |
+
+Run `cdd-kit detect-stack` to verify the detected tech stack.

package/assets/agents/backend-engineer.md

@@ -17,7 +17,7 @@ Before editing production code, read the change artifacts, API/env/data/business
 - Validate input at the boundary.
 - Return standardized errors, not raw exceptions.
 - Preserve backward compatibility unless the spec explicitly marks a breaking change.
-- Add tests before or alongside implementation according to the test plan.
+- **TDD**: Read `specs/changes/<id>/test-plan.md` first. Write failing unit, contract, and integration tests BEFORE writing feature code. Tests in `tasks.md` items 3.1–3.2 are your responsibility.
 - Update CI/CD workflows when required by `ci-gates.md`.
 
 ## Common pitfalls
@@ -30,10 +30,21 @@ Before editing production code, read the change artifacts, API/env/data/business
 - Read-after-write consistency — a write followed by an immediate read on a replica may return stale data.
 - Pagination — always sort by a stable column + tie-breaker (id), never offset-paginate over mutable data.
 
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
+- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
 ## Handoff
 
 Report changed files, contract updates, tests added, commands run, known risks, and next reviewer.
 
+## Artifact discipline
+
+Implementation code goes into source files. Do NOT write runnable code into any `specs/changes/<id>/` artifact.
+In your agent log, reference file paths and function names — do not paste code blocks.
+
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
@@ -65,3 +76,10 @@ with this exact structure (lines starting with `- ` are required):
 - Evidence must be concrete: file:line, command name + last-10-line stdout,
   contract path + section, test name, etc. NEVER write "verified" or "OK"
   without a pointer.
+
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, `specs/changes/<current-change-id>/`
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
+Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.

package/assets/agents/change-classifier.md

@@ -9,6 +9,17 @@ You are the change classifier for Contract-Driven Delivery.
 
 Your job is to stop premature implementation. Read the user request and nearby project context, then produce a classification report.
 
+## Tier mapping
+
+| Risk Level | Impact Radius | Tier |
+|---|---|---|
+| critical or high | system-wide or cross-module | 0–1 |
+| medium | cross-module or module-level | 2–3 |
+| low | module-level or isolated | 3–4 |
+| low | docs / prompts / config only, no behavior change | 4–5 |
+
+When in doubt, classify upward.
+
 ## Output
 
 Use this structure:
@@ -26,15 +37,30 @@ Use this structure:
 ## Impact Radius
 - isolated / module-level / cross-module / system-wide
 
+## Tier
+- 0 / 1 / 2 / 3 / 4 / 5
+
+## Architecture Review Required
+- yes / no
+- reason: (fill only if yes)
+
 ## Required Artifacts
-- request.md:
-- current-behavior.md:
-- proposal.md:
-- spec.md:
-- design.md:
-- contracts.md:
-- test-plan.md:
-- ci-gates.md:
+
+The following 5 artifacts are always required for implementation changes:
+`change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.md`
+
+## Optional Artifacts (default: no — set yes only with explicit reason)
+
+| artifact | create? | reason |
+|---|---|---|
+| current-behavior.md | no | |
+| proposal.md | no | |
+| spec.md | no | |
+| design.md | no | |
+| qa-report.md | no | |
+| regression-report.md | no | |
+
+Note: `archive.md` is created during change close-out, not at classification time.
 
 ## Required Contracts
 - API:
@@ -59,6 +85,16 @@ Use this structure:
 ## Required Agents
 ...
 
+## Inferred Acceptance Criteria
+(List 3-8 testable acceptance criteria derived from the change request. Format: `AC-N: <criterion>`. These will be used by test-strategist to populate the Acceptance Criteria → Test Mapping table.)
+- AC-1:
+- AC-2:
+- AC-3:
+
+## Tasks Not Applicable
+(List task IDs from tasks.md that are NOT applicable to this change, using the format `2.2, 2.3, 4.2`. Main Claude will mark these as [-] in tasks.md.)
+- not-applicable:
+
 ## Clarifications or Assumptions
 ...
 ```

package/assets/agents/ci-cd-gatekeeper.md

@@ -56,6 +56,12 @@ CI/CD is mandatory. Every change must have a `ci-gates.md` plan, even if the pla
 mergeable / blocked / informational-risk
 ```
 
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
+- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
@@ -87,3 +93,10 @@ with this exact structure (lines starting with `- ` are required):
 - Evidence must be concrete: file:line, command name + last-10-line stdout,
   contract path + section, test name, etc. NEVER write "verified" or "OK"
   without a pointer.
+
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, `specs/changes/<current-change-id>/`
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
+Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.

package/assets/agents/contract-reviewer.md

@@ -55,6 +55,12 @@ Record dependency or migration impacts in `contracts.md` only as contract-level
 approved / changes-required
 ```
 
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
+- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
 ## Machine-Verifiable Evidence
 
 After completing your task, include an **## Agent Log** section at the end of your response with this exact structure (lines starting with `- ` are required). The calling skill will write this block to `specs/changes/<change-id>/agent-log/contract-reviewer.md`.
@@ -86,3 +92,10 @@ After completing your task, include an **## Agent Log** section at the end of yo
 - Evidence must be concrete: file:line, command name + last-10-line stdout,
   contract path + section, test name, etc. NEVER write "verified" or "OK"
   without a pointer.
+
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, `specs/changes/<current-change-id>/`
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
+Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.

package/assets/agents/e2e-resilience-engineer.md

@@ -33,6 +33,12 @@ Your tests must prove that real user journeys and realistic failure modes behave
 
 Record test files, scenarios, fixtures/mocks, commands, screenshots/videos, and mutation checks.
 
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
+- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
@@ -64,3 +70,10 @@ with this exact structure (lines starting with `- ` are required):
 - Evidence must be concrete: file:line, command name + last-10-line stdout,
   contract path + section, test name, etc. NEVER write "verified" or "OK"
   without a pointer.
+
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, `specs/changes/<current-change-id>/`
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
+Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.

package/assets/agents/frontend-engineer.md

@@ -16,7 +16,7 @@ Before editing, read the change artifacts, API contract, CSS/UI contract, compon
 - Do not bypass shared component rules.
 - Handle loading, empty, error, disabled, long text, no permission, and slow network states when applicable.
 - Be aware of monkey-class bugs (double submit, rapid actions, navigation state, hidden tab); the actual preventive specs and tests are owned by monkey-test-engineer.
-- Add or update E2E/visual/data-boundary/resilience tests when UI behavior changes.
+- **TDD**: Read `specs/changes/<id>/test-plan.md` first. Write failing unit and component tests BEFORE writing feature code. E2E, visual, and data-boundary tests are also your responsibility when UI behavior changes. Tasks.md items 3.1–3.2 include frontend test scope.
 
 ## Common pitfalls
 
@@ -28,10 +28,21 @@ Before editing, read the change artifacts, API contract, CSS/UI contract, compon
 - Bundle size — dynamic import heavy routes; avoid full lodash / moment imports.
 - Note: avoid double-submit / rapid-action implementation bugs — but do not author monkey tests here; that is `monkey-test-engineer`'s scope.
 
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
+- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
 ## Handoff
 
 Report changed screens, component states covered, screenshots/videos if generated, tests added, commands run, and remaining UI risks.
 
+## Artifact discipline
+
+Implementation code goes into source files. Do NOT write runnable code into any `specs/changes/<id>/` artifact.
+In your agent log, reference file paths and function names — do not paste code blocks.
+
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
@@ -63,3 +74,10 @@ with this exact structure (lines starting with `- ` are required):
 - Evidence must be concrete: file:line, command name + last-10-line stdout,
   contract path + section, test name, etc. NEVER write "verified" or "OK"
   without a pointer.
+
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, `specs/changes/<current-change-id>/`
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
+Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.

package/assets/agents/monkey-test-engineer.md

@@ -36,6 +36,12 @@ Use fuzz payloads, Playwright action sequences, property-based tests, and target
 - Adversarial corpora — common boundaries (empty, max-int, NaN, Unicode RTL, Zero-Width Joiner, surrogate pairs, BOM); SQL/JS injection strings.
 - Determinism — every monkey test must seed its randomness; record the seed on failure for replay.
 
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
+- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
@@ -66,3 +72,10 @@ with this exact structure (lines starting with `- ` are required):
 - Evidence must be concrete: file:line, command name + last-10-line stdout,
   contract path + section, test name, etc. NEVER write "verified" or "OK"
   without a pointer.
+
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, `specs/changes/<current-change-id>/`
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
+Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.

package/assets/agents/qa-reviewer.md

@@ -67,6 +67,12 @@ Invoke `spec-drift-auditor` at the following points (do not wait for issues to s
 approved / blocked / approved-with-risk
 ```
 
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
+- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
 ## Machine-Verifiable Evidence
 
 After completing your task, include an **## Agent Log** section at the end of your response with this exact structure (lines starting with `- ` are required). The calling skill will write this block to `specs/changes/<change-id>/agent-log/qa-reviewer.md`.
@@ -99,3 +105,10 @@ After completing your task, include an **## Agent Log** section at the end of yo
 - Evidence must be concrete: file:line, command name + last-10-line stdout,
   contract path + section, test name, etc. NEVER write "verified" or "OK"
   without a pointer.
+
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, `specs/changes/<current-change-id>/`
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
+Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.

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

@@ -22,6 +22,9 @@ Inspect the repository and produce a project profile before implementation or st
 - CI/CD workflows
 - worker/cache/database/storage configuration
 
+**Do NOT read `specs/changes/` or `specs/archive/`.** Those are passive history records. Inspect only live sources: source code, package files, contracts/, tests/, CI workflows, and CLAUDE.md.
+Also do not read specs/templates/ — those are scaffolding stubs, not live project state.
+
 ## Detection extras
 
 - Monorepo / workspace — check `pnpm-workspace.yaml`, `lerna.json`, `nx.json`, `turbo.json`, `go.work`, `pyproject.toml [tool.uv]` workspaces.

package/assets/agents/spec-architect.md

@@ -49,45 +49,48 @@ proposed / accepted / superseded
 
 ## Output
 
-```md
-# Architecture Impact Report
+Write to `specs/changes/<change-id>/design.md` using this structure:
 
-## Summary
-...
+```markdown
+# Design: <change-id>
 
-## Architecture Impact
-- yes / no / uncertain
-
-## Affected Areas
-- frontend:
-- backend:
-- database:
-- cache/queue:
-- auth/permission:
-- API contract:
-- CSS/UI system:
-- env/deploy:
-- CI/CD:
-
-## Options
-### Option A
-...
-### Option B
-...
+## Summary
+(1 paragraph: what changes architecturally and why)
 
-## Recommendation
-...
+## Affected Components
+| component | file path(s) | nature of change |
+|---|---|---|
 
-## ADR Required
-yes (written to docs/adr/...) / no
+## Key Decisions
+- **Decision**: rationale — rejected alternative: reason rejected
 
-## Required Follow-up Artifacts
-...
+## Migration / Rollback
+(Prose description. SQL and code go in migration files, not here.)
 
-## Risks and Mitigations
-...
+## Open Risks
 ```
 
+## Output discipline
+
+Your output goes into `specs/changes/<id>/design.md`. It must capture architectural decisions — not implement them.
+
+- **DO** write: 1-paragraph architecture summary
+- **DO** write: affected components table (component | file path | nature of change)
+- **DO** write: key decisions and rejected alternatives in prose
+- **DO** write: migration/rollback strategy in prose
+- **DO NOT** write: SQL DDL or migration scripts (those go in migrations/)
+- **DO NOT** write: ORM model code, API handler code, or any runnable code block > 10 lines
+- **DO NOT** write: storage estimates, benchmark numbers, or detailed implementation steps
+
+Reference file paths instead of duplicating implementation content.
+Target: `design.md` ≤ 150 lines.
+
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
+- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
@@ -119,3 +122,10 @@ with this exact structure (lines starting with `- ` are required):
 - Evidence must be concrete: file:line, command name + last-10-line stdout,
   contract path + section, test name, etc. NEVER write "verified" or "OK"
   without a pointer.
+
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, `specs/changes/<current-change-id>/`
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
+Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.