its-magic 0.1.2 → 0.1.3-1

package/template/docs/engineering/runbook.md

@@ -247,40 +247,58 @@ Normative contract: `decisions/DEC-0083.md`, `docs/engineering/architecture.md`
 implementation changes — distinct from **US-0065** phase QA, **US-0086** test routing, and
 **US-0067** release hints. Default-off scratchpad gate; **no** `.env` reads (**US-0085**).
 
+**Install-time bootstrap (US-0099):** on **`missing`**, **`upgrade`**, and **npm `postinstall`**, the
+framework copies **`template/.cursor/dev-environment.json.example`** → resolved profile path
+(**`.cursor/dev-environment.json`** by default) **only when the target file is absent** — never
+overwrites operator-customized profiles. Customize **after** bootstrap (compose **`service`**, **`*Env`**
+connect refs); manual copy is no longer a prerequisite to enable the gate.
+
+| Before (US-0098) | After (US-0099) |
+|------------------|-----------------|
+| "Seed profile" = manual copy prerequisite | Bootstrap automatic on install/upgrade/postinstall |
+| **`DEV_ENV_PROFILE_MISSING`** → manual copy first | Troubleshooting references auto-bootstrap + customize-after-bootstrap |
+
 ### Operator recipes
 
 | Scenario | Operator action |
 |----------|-----------------|
 | Enable dev auto-launch | Set **`DEV_AUTO_LAUNCH_PROFILE=deterministic_v1`** in scratchpad |
-| Seed profile | Copy **`template/.cursor/dev-environment.json.example`** → **`.cursor/dev-environment.json`**; set compose **`service`** + **`*Env`** connect refs |
+| Customize profile after bootstrap | Edit **`.cursor/dev-environment.json`** copied from example; set compose **`service`** + **`*Env`** connect refs |
 | Force relaunch | Send exact phrase **`refresh dev environment`** (case-sensitive whole phrase) |
 | Profile off / manual mode | Leave **`DEV_AUTO_LAUNCH_PROFILE=off`** (default) — execute step **24** zero overhead |
 | Ambiguous stack | Fix compose path or seed profile; remediate **`DEV_ENV_DETECT_AMBIGUOUS`** |
 | Remote + local both on | **US-0086** remote wins over **docker-host-local** — see precedence in **`DEC-0084`** §3 |
 | Bind-mount hot reload | Default skip on source-only docker changes; use refresh or **`restart_on_source_change=true`** |
+| Global npm install (no consumer repo) | **`[DEV_ENV_BOOTSTRAP_SKIP] no consumer repository detected`** — run **`its-magic`** install into target repo |
 
 ### Troubleshooting (`DEV_ENV_*` reason codes)
 
+**Bootstrap family (install-time; distinct from runtime profile/relaunch families):**
+**`DEV_ENV_BOOTSTRAP_COPIED`**, **`DEV_ENV_BOOTSTRAP_SKIPPED_EXISTS`**, **`DEV_ENV_BOOTSTRAP_PATH_INVALID`**,
+**`DEV_ENV_BOOTSTRAP_SOURCE_MISSING`**.
+
 **Profile family:** **`DEV_ENV_PROFILE_DISABLED`**, **`DEV_ENV_PROFILE_INVALID`**,
-**`DEV_ENV_PROFILE_MISSING`**, **`DEV_ENV_DETECT_AMBIGUOUS`**, **`DEV_ENV_COMPOSE_UNRESOLVED`**,
-**`DEV_ENV_TARGET_DISABLED`**, **`DEV_ENV_SECRET_SURFACE_VIOLATION`**.
+**`DEV_ENV_PROFILE_MISSING`** (if bootstrap skipped or profile deleted — re-run install/upgrade or
+**`python scripts/dev_environment_lib.py --bootstrap --target <repo>`** then customize),
+**`DEV_ENV_DETECT_AMBIGUOUS`**, **`DEV_ENV_COMPOSE_UNRESOLVED`**, **`DEV_ENV_TARGET_DISABLED`**, **`DEV_ENV_SECRET_SURFACE_VIOLATION`**.
 
 **Relaunch family:** **`DEV_ENV_RELAUNCH_SKIPPED_NO_SURFACE`**, **`DEV_ENV_RELAUNCH_SKIPPED_PROFILE_OFF`**,
-**`DEV_ENV_RELAUNCH_FAILED`**, **`DEV_ENV_RELAUNCH_RETRY_EXHAUSTED`**, **`DEV_ENV_RELAUNCH_TIMEOUT`**,
-**`DEV_ENV_CONNECT_UNAVAILABLE`**.
+**`DEV_ENV_RELAUNCH_FAILED`**, **`DEV_ENV_RELAUNCH_RETRY_EXHAUSTED`**, **`DEV_ENV_RELAUNCH_TIMEOUT`**, **`DEV_ENV_CONNECT_UNAVAILABLE`**.
 
 ### Commands
 
 ```bash
 python scripts/dev_environment_lib.py --self-test
 python scripts/dev_environment_lib.py --load .cursor/dev-environment.json
+python scripts/dev_environment_lib.py --bootstrap --target .
 python scripts/check_intake_template_parity.py --scope=dev-environment
 pytest -k us0098 tests/auto_command_contract_test.py
+pytest -k us0099 tests/auto_command_contract_test.py
 ```
 
 Implementation tranche order: **A** (schema + scratchpad) → **B** (stdlib helper) → **C** (execute step **24** + docs) → **D** (contract tests + parity + harness).
 
-Normative contract: `decisions/DEC-0084.md`, `docs/engineering/architecture.md` `# US-0098`.
+Normative contract: `decisions/DEC-0084.md`, `docs/engineering/architecture.md` `# US-0098`, `# US-0099` (bootstrap posture).
 
 ## User-visible internal metadata guard (US-0071 / DEC-0053)
 
@@ -632,6 +650,203 @@ When **`AUTO_DELIVERY_ROUTING=backlog_then_scratchpad`**, story row may declare
 
 **Release status (S0086 / US-0096)**: **`released`** (`2026-06-13T16:00:00Z`); **`US-0096`** **DONE** in canonical backlog. Operator verify: **`handoffs/releases/S0086-release-notes.md`** **## Verify**; publish skipped while **`RELEASE_PUBLISH_MODE=confirm`**.
 
+## Per-phase model tier selection (US-0101 / DEC-0086)
+
+`MODEL_TIER` selects LLM model strength (which model runs per lifecycle phase).
+Three operator-facing tiers map to stable Cursor aliases — no vendor slugs in
+template files.
+
+| Key | Values | Default | Role |
+|-----|--------|---------|------|
+| **`MODEL_TIER_DEFAULT`** | `cheap` \| `balanced` \| `strong` | `balanced` | Fallback when phase-specific key absent |
+| **`MODEL_TIER_<PHASE>`** | `cheap` \| `balanced` \| `strong` | *(per matrix)* | Per-phase tier override |
+| **`MODEL_CATALOG`** | path | `.cursor/model-catalog.local.json` | Path to local slug catalog |
+| **`MODEL_RESOLVE`** | `alias_only` \| `local_catalog` | `alias_only` | Resolution strategy |
+| **`MODEL_FALLBACK`** | `inherit` | `inherit` | Fallback when catalog lookup fails |
+| **`MODEL_PROVIDER_MODE`** | `cursor` \| `api` | `cursor` | Provider routing |
+
+### Default phase→tier matrix (architecture-locked)
+
+| Tier | Cursor alias | `model:` field | Phases |
+|------|-------------|----------------|--------|
+| **`cheap`** | `fast` | `model: fast` | `ask`, `refresh-context`, `memory-audit`, `status-reconcile`, `pause` |
+| **`balanced`** | `inherit` | `model: inherit` | `intake`, `discovery`, `research`, `release`, `plan-verify` |
+| **`strong`** | *(omit)* | no `model:` field | `architecture`, `execute`, `quick`, `qa`, `verify-work`, `security-review` |
+| *(inherit parent)* | — | — | `auto` (orchestrator always inherits parent model) |
+
+### Provider mode (MODEL_PROVIDER_MODE)
+
+| Mode | Description |
+|------|-------------|
+| **`cursor`** (default) | All subagents route through Cursor-managed infrastructure; tier aliases work as designed |
+| **`api`** | Operator uses BYOK via Cursor Settings → Models → API Key |
+
+**Known limitation (confirmed 2026-06)**: Cursor subagents do **NOT** inherit
+custom API keys or base URLs — they always bill against the Cursor plan. When
+`MODEL_PROVIDER_MODE=api`, the local catalog is the only operator-controlled
+surface; subagent `model:` aliases still resolve through Cursor infrastructure.
+
+**Workaround recipes**:
+
+1. **Parent model + `inherit`** — set the parent chat model to the desired BYOK
+   model; subagents using `model: inherit` (balanced tier) pick it up.
+2. **Manual phase runs** — run each phase in a separate chat with the desired
+   model selected at the chat level (no subagent spawn).
+3. **Local catalog override** — set `MODEL_RESOLVE=local_catalog` and populate
+   `.cursor/model-catalog.local.json` with vendor slugs; materializer applies
+   slugs at template materialization time (not at subagent runtime).
+
+### Non-substitution paragraph
+
+MODEL_TIER ≠ TOKEN_PROFILE ≠ DELIVERY_MODE
+
+> **`MODEL_TIER`** selects LLM model strength (which model runs).
+> **`TOKEN_PROFILE`** selects context breadth / token cost (how much context the model sees).
+> **`DELIVERY_MODE`** selects lifecycle shape (standard / ultra_lean / mega_quick).
+> These are **independent axes** — none substitutes for another. A `strong` tier
+> with `lean` profile is valid; a `cheap` tier with `full` profile is valid.
+> Setting one does not change the others. Combine freely.
+
+### Reason codes — `MODEL_TIER_*` / `MODEL_CATALOG_*` / `MODEL_RESOLVE_*` / `MODEL_SLUG_*`
+
+| Code | Trigger |
+|------|---------|
+| **`MODEL_TIER_INVALID`** | Unknown tier value (not `cheap`/`balanced`/`strong`) |
+| **`MODEL_CATALOG_INVALID`** | Malformed catalog JSON (parse error, missing `schema_version`) |
+| **`MODEL_SLUG_UNKNOWN`** | Tier key missing from catalog when `MODEL_RESOLVE=local_catalog` |
+| **`MODEL_RESOLVE_FALLBACK`** | Catalog lookup failed but `MODEL_FALLBACK=inherit` → reason + fallback |
+
+### Template agent defaults
+
+| Agent role | Tier | `model:` field |
+|-----------|------|----------------|
+| `curator` | cheap | `model: fast` |
+| `po` | balanced | `model: inherit` |
+| `release` | balanced | `model: inherit` |
+| `tech-lead` | strong | *(omit)* |
+| `dev` | strong | *(omit)* |
+| `qa` | strong | *(omit)* |
+| `security` | strong | *(omit)* |
+
+**Forbidden in `template/.cursor/agents/`**: hardcoded vendor slugs
+(`composer-*`, `claude-*`, `gpt-*`, `opus-*`). Template files use aliases only.
+
+### Local catalog schema (v1)
+
+```json
+{
+  "schema_version": 1,
+  "tiers": {
+    "cheap": "<slug>",
+    "balanced": "<slug>",
+    "strong": "<slug>"
+  },
+  "notes": "optional free-text"
+}
+```
+
+- Path: `.cursor/model-catalog.local.json` (gitignored)
+- Example: `.cursor/model-catalog.local.example.json` (committed, placeholder values)
+- All three tier keys required; values are opaque vendor slug strings
+
+### Resolver algorithm
+
+1. Read `MODEL_TIER_<PHASE>` from merged scratchpad → tier value
+2. If `MODEL_RESOLVE=alias_only` (default): use built-in mapping (table above)
+3. If `MODEL_RESOLVE=local_catalog`: load catalog JSON → lookup tier key → slug
+4. If key missing → `MODEL_SLUG_UNKNOWN` fail-closed
+5. If `MODEL_FALLBACK=inherit` and lookup fails → emit `MODEL_RESOLVE_FALLBACK` + use `inherit`
+6. Unknown tier value → `MODEL_TIER_INVALID` fail-closed
+7. Malformed catalog JSON → `MODEL_CATALOG_INVALID` fail-closed
+
+### Validation commands
+
+- `python scripts/model_tier_validate.py --repo .`
+- `pytest -k us0101 tests/auto_command_contract_test.py`
+- `python scripts/check_intake_template_parity.py --scope=model-tier`
+- `tests/run-tests.ps1` / `tests/run-tests.sh` §26Z
+
+Normative architecture: `docs/engineering/architecture.md` (**# US-0101**).
+
+## Direct per-phase model slug override + role catalog (US-0102 / DEC-0087)
+
+Composes on **US-0101** / **DEC-0086** — tier-only operators need no migration.
+
+### 5-step precedence chain
+
+| Step | Source | Outcome |
+|------|--------|---------|
+| **1** | `MODEL_<PHASE>` | Non-empty slug → return (validate per mode) or `MODEL_OVERRIDE_SLUG_UNKNOWN` |
+| **2** | `MODEL_TIER_<PHASE>` | **DEC-0086** tier→alias / `local_catalog` chain |
+| **3** | `MODEL_RESOLVE=role_catalog` | Phase→logical role → catalog `roles[<key>]`; miss → `MODEL_ROLE_SLUG_UNKNOWN` → fall through |
+| **4** | `MODEL_TIER_DEFAULT` | **DEC-0086** tier chain |
+| **5** | Cursor alias | **DEC-0086** built-in mapping |
+
+When `MODEL_RESOLVE` is `alias_only` or `local_catalog`, step **3** is skipped.
+
+### Scratchpad keys (new)
+
+| Key | Default | Role |
+|-----|---------|------|
+| **`MODEL_<PHASE>`** | *(absent)* | Direct vendor slug; includes `MODEL_ASK` |
+| **`MODEL_RESOLVE`** | `alias_only` | Extended: `alias_only` \| `local_catalog` \| **`role_catalog`** |
+
+Operator slugs live in `.cursor/scratchpad.local.md` and `.cursor/model-catalog.local.json` only (gitignored).
+
+### Role catalog enablement recipe
+
+1. Copy a v2 example catalog:
+   - `.cursor/model-catalog.local.example.role-based-balanced.json`, or
+   - `.cursor/model-catalog.local.example.role-based-highend.json`
+2. Save as `.cursor/model-catalog.local.json` with real vendor slugs.
+3. Set `MODEL_RESOLVE=role_catalog` in `.cursor/scratchpad.local.md`.
+4. Optional: set `MODEL_<PHASE>=<slug>` for direct overrides (step 1 wins over role lookup).
+5. Run `python scripts/model_tier_validate.py --repo .` to validate.
+
+On role lookup miss → `MODEL_ROLE_SLUG_UNKNOWN` emitted; resolver falls through to `MODEL_TIER_DEFAULT` then Cursor alias.
+
+**`dev_difficult`**: no automatic phase routing — use `MODEL_EXECUTE=<slug>` direct override or tier `strong` + catalog tier slug.
+
+Non-normative role recommendations: `ai_modell_auslegung_cursor_highend.md`.
+
+### Catalog schema v2 (opt-in)
+
+```json
+{
+  "schema_version": 2,
+  "tiers": { "cheap": "<slug>", "balanced": "<slug>", "strong": "<slug>" },
+  "roles": {
+    "po": "<slug>", "sa": "<slug>", "dev": "<slug>", "dev_difficult": "<slug>",
+    "qa": "<slug>", "security": "<slug>", "release": "<slug>"
+  }
+}
+```
+
+v1 catalogs (tiers only) unchanged. Malformed v2 → `MODEL_CATALOG_SCHEMA_V2_INVALID`.
+
+### New reason codes
+
+| Code | Trigger |
+|------|---------|
+| **`MODEL_OVERRIDE_SLUG_UNKNOWN`** | Direct slug validation failure |
+| **`MODEL_ROLE_SLUG_UNKNOWN`** | Role catalog lookup miss |
+| **`MODEL_CATALOG_SCHEMA_V2_INVALID`** | v2 schema validation failure |
+
+### Non-substitution paragraph
+
+MODEL_TIER ≠ TOKEN_PROFILE ≠ DELIVERY_MODE — unchanged from **US-0101**; model selection is orthogonal to context breadth.
+
+### Validation commands
+
+- `python scripts/model_tier_validate.py --repo .`
+- `pytest -k us0102 tests/auto_command_contract_test.py`
+- `python scripts/check_intake_template_parity.py --scope=model-tier-overrides`
+- `tests/run-tests.ps1` / `tests/run-tests.sh` §26AA
+
+Normative architecture: `docs/engineering/architecture.md` (**# US-0102**); decision: **`DEC-0087`**.
+
+Binding decision: `decisions/DEC-0086.md`.
+
 Context compaction policy:
 
 - `docs/engineering/state.md` is a compact hot surface for current execution
@@ -792,6 +1007,59 @@ Fail-closed reason codes:
 - `RELEASE_OPERATOR_HINTS_AMBIGUOUS`
 - `RELEASE_OPERATOR_HINTS_SECRET_EXPOSURE`
 
+## Version-scoped release docs (US-0100 / DEC-0085)
+
+Cumulative and per-version release documentation compose with **US-0040** sprint
+notes — they do **not** replace `handoffs/releases/Sxxxx-release-notes.md`.
+
+| Artifact | Path | Role |
+|----------|------|------|
+| Cumulative changelog | `CHANGELOG.md` | Keep a Changelog 1.1.0; mandatory top `## [Unreleased]` |
+| Per-version GitHub body | `handoffs/releases/{semver}-release-notes.md` | **`gh -F` SOT** (semver stem without `v`) |
+| Sprint workflow evidence | `handoffs/releases/Sxxxx-release-notes.md` | Unchanged (**US-0040**); derivation input only |
+| Backfill manifest | `docs/engineering/context/release-version-backfill.manifest.yaml` | Tier B operator `sprint_id`→`semver` overrides |
+
+### Operator workflow (deterministic order)
+
+1. **`/release`** (local workflow): after step **9** finalization, step **19**
+   derives work items, writes version docs when semver known, or appends
+   `[Unreleased]` only when semver blank.
+2. **`release-all.sh`** (npm/choco/brew + GitHub): post-`npm version`, ensure
+   `handoffs/releases/${NEW_VERSION}-release-notes.md`, run
+   `release_changelog_validate.py --enforce`, then `gh release create -F`.
+3. **CI tag push** (when **US-0054** publish targets enabled): same `-F` path;
+   confirmation gates unchanged.
+
+### Scratchpad keys
+
+| Key | Default | Role |
+|-----|---------|------|
+| `RELEASE_CHANGELOG_ENFORCE` | `1` | Blocking validator at `/release` step **19d** + `release-all.sh` |
+| `RELEASE_CHANGELOG_ALLOW_GENERATE_NOTES` | `0` | Opt-in `gh --generate-notes` when version doc missing |
+
+### Backfill tiers (one-time / idempotent)
+
+| Tier | Source | Semver |
+|------|--------|--------|
+| A | Queue `release_version` non-empty | As-is |
+| B | `release-version-backfill.manifest.yaml` | Operator map |
+| C | Remaining released rows | Synthetic `0.0.0-wf.{NNN}` (`S0089`→`0.0.0-wf.089`) |
+
+Run: `python scripts/release_changelog_backfill.py --repo .` (idempotent).
+Ambiguous manifest collision → `RELEASE_CHANGELOG_BACKFILL_AMBIGUOUS`.
+
+### Troubleshooting (`RELEASE_CHANGELOG_*`)
+
+| Code | Remediation |
+|------|-------------|
+| `RELEASE_CHANGELOG_VERSION_DOC_MISSING` | Run `build_version_doc` / backfill `--ensure-version` before `gh -F` |
+| `RELEASE_CHANGELOG_UNRELEASED_MISSING` | Add `## [Unreleased]` header to `CHANGELOG.md` |
+| `RELEASE_CHANGELOG_QUEUE_DRIFT` | Re-run `bind_queue_release_version` for target sprints |
+| `RELEASE_CHANGELOG_BACKFILL_AMBIGUOUS` | Fix manifest duplicate semver mapping |
+
+Contract tests: `pytest -k us0100 tests/auto_command_contract_test.py`; parity:
+`python scripts/check_intake_template_parity.py --scope=release-changelog`.
+
 ## Deterministic status reconciliation mode (US-0055 / DEC-0037)
 
 Use the dedicated reconciliation command to normalize status drift across

package/template/handoffs/releases/vX.Y.Z-release-notes.md.example

@@ -0,0 +1,21 @@
+# Per-version release notes — pattern example (US-0100 / DEC-0085)
+
+> **Rename at use**: copy this file to `handoffs/releases/{semver}-release-notes.md`
+> where `{semver}` is the normalized semver stem **without** a leading `v`
+> (e.g. `0.1.2-41-release-notes.md`, not `v0.1.2-41-release-notes.md`).
+>
+> **Do not overwrite** unrelated version files — target only the semver you are publishing.
+> Sprint-scoped workflow evidence stays in `handoffs/releases/Sxxxx-release-notes.md`
+> (**US-0040**); never pass `Sxxxx` notes to `gh -F`.
+
+## Work items
+
+- **US-xxxx** — One-line summary derived from sprint notes / backlog / queue precedence.
+- **BUG-xxxx** — One-line fix summary (category **Fixed** in cumulative `CHANGELOG.md`).
+
+## Sprint evidence
+
+- [`S0070`](handoffs/releases/S0070-release-notes.md)
+- [`S0071`](handoffs/releases/S0071-release-notes.md)
+
+<!-- Example coalesce: S0070 + S0071 → semver 0.1.2-41 -->

package/template/scripts/check_intake_template_parity.py

@@ -202,6 +202,90 @@ DEV_ENVIRONMENT_PAIRS: tuple[tuple[str, str], ...] = (
     ),
 )
 
+RELEASE_CHANGELOG_PAIRS: tuple[tuple[str, str], ...] = (
+    (
+        "scripts/release_changelog_lib.py",
+        "template/scripts/release_changelog_lib.py",
+    ),
+    (
+        "scripts/release_changelog_validate.py",
+        "template/scripts/release_changelog_validate.py",
+    ),
+    (
+        "scripts/release_changelog_backfill.py",
+        "template/scripts/release_changelog_backfill.py",
+    ),
+    ("CHANGELOG.md", "template/CHANGELOG.md"),
+    (".cursor/commands/release.md", "template/.cursor/commands/release.md"),
+    ("scripts/release-all.sh", "template/scripts/release-all.sh"),
+    (
+        "template/handoffs/releases/vX.Y.Z-release-notes.md.example",
+        "template/handoffs/releases/vX.Y.Z-release-notes.md.example",
+    ),
+    (
+        "scripts/check_intake_template_parity.py",
+        "template/scripts/check_intake_template_parity.py",
+    ),
+)
+
+MODEL_TIER_PAIRS: tuple[tuple[str, str], ...] = (
+    (
+        "scripts/model_tier_lib.py",
+        "template/scripts/model_tier_lib.py",
+    ),
+    (
+        "scripts/model_tier_validate.py",
+        "template/scripts/model_tier_validate.py",
+    ),
+    (
+        "docs/engineering/runbook.md",
+        "template/docs/engineering/runbook.md",
+    ),
+    (
+        ".cursor/scratchpad.md",
+        "template/.cursor/scratchpad.md",
+    ),
+    (
+        ".cursor/scratchpad.local.example.md",
+        "template/.cursor/scratchpad.local.example.md",
+    ),
+    (
+        "scripts/check_intake_template_parity.py",
+        "template/scripts/check_intake_template_parity.py",
+    ),
+)
+
+MODEL_TIER_OVERRIDES_PAIRS: tuple[tuple[str, str], ...] = (
+    (
+        ".cursor/scratchpad.md",
+        "template/.cursor/scratchpad.md",
+    ),
+    (
+        ".cursor/scratchpad.local.example.md",
+        "template/.cursor/scratchpad.local.example.md",
+    ),
+    (
+        ".cursor/model-catalog.local.example.role-based-balanced.json",
+        "template/.cursor/model-catalog.local.example.role-based-balanced.json",
+    ),
+    (
+        ".cursor/model-catalog.local.example.role-based-highend.json",
+        "template/.cursor/model-catalog.local.example.role-based-highend.json",
+    ),
+    (
+        "scripts/model_tier_lib.py",
+        "template/scripts/model_tier_lib.py",
+    ),
+    (
+        "scripts/model_tier_validate.py",
+        "template/scripts/model_tier_validate.py",
+    ),
+    (
+        "docs/engineering/runbook.md",
+        "template/docs/engineering/runbook.md",
+    ),
+)
+
 DOWNSTREAM_CI_GUARD_PAIRS: tuple[tuple[str, str], ...] = (
     (
         "scripts/check_downstream_ci_guard.py",
@@ -225,6 +309,9 @@ SCOPES: dict[str, tuple[tuple[str, str], ...]] = {
     "us-0096": US0096_PAIRS,
     "project-readme": PROJECT_README_PAIRS,
     "dev-environment": DEV_ENVIRONMENT_PAIRS,
+    "release-changelog": RELEASE_CHANGELOG_PAIRS,
+    "model-tier": MODEL_TIER_PAIRS,
+    "model-tier-overrides": MODEL_TIER_OVERRIDES_PAIRS,
     "all": (
         INTAKE_TEMPLATE_PAIRS
         + CAVEMAN_COMPRESS_PAIRS
@@ -237,6 +324,9 @@ SCOPES: dict[str, tuple[tuple[str, str], ...]] = {
         + US0096_PAIRS
         + PROJECT_README_PAIRS
         + DEV_ENVIRONMENT_PAIRS
+        + RELEASE_CHANGELOG_PAIRS
+        + MODEL_TIER_PAIRS
+        + MODEL_TIER_OVERRIDES_PAIRS
     ),
 }
 

package/template/scripts/dev_environment_lib.py

@@ -9,6 +9,7 @@ import fnmatch
 import json
 import os
 import re
+import shutil
 import subprocess
 import sys
 from pathlib import Path
@@ -62,6 +63,24 @@ RELAUNCH_REASON_CODES = (
     DEV_ENV_CONNECT_UNAVAILABLE,
 )
 
+# DEV_ENV_BOOTSTRAP_* reason codes (DEC-0084 § bootstrap posture / US-0099)
+DEV_ENV_BOOTSTRAP_COPIED = "DEV_ENV_BOOTSTRAP_COPIED"
+DEV_ENV_BOOTSTRAP_SKIPPED_EXISTS = "DEV_ENV_BOOTSTRAP_SKIPPED_EXISTS"
+DEV_ENV_BOOTSTRAP_PATH_INVALID = "DEV_ENV_BOOTSTRAP_PATH_INVALID"
+DEV_ENV_BOOTSTRAP_SOURCE_MISSING = "DEV_ENV_BOOTSTRAP_SOURCE_MISSING"
+
+BOOTSTRAP_REASON_CODES = (
+    DEV_ENV_BOOTSTRAP_COPIED,
+    DEV_ENV_BOOTSTRAP_SKIPPED_EXISTS,
+    DEV_ENV_BOOTSTRAP_PATH_INVALID,
+    DEV_ENV_BOOTSTRAP_SOURCE_MISSING,
+)
+
+SCRATCHPAD_EXAMPLE_REL = ".cursor/scratchpad.local.example.md"
+SCRATCHPAD_BASELINE_REL = ".cursor/scratchpad.md"
+SCRATCHPAD_LOCAL_REL = ".cursor/scratchpad.local.md"
+DEV_ENV_EXAMPLE_REL = ".cursor/dev-environment.json.example"
+
 TIER_A_PATTERNS = (
     "Dockerfile",
     "Dockerfile.*",
@@ -110,6 +129,110 @@ def _normalize_path(path: str) -> str:
     return path.replace("\\", "/")
 
 
+def _parse_scratchpad_file(path: Path) -> Dict[str, str]:
+    if not path.is_file():
+        return {}
+    out: Dict[str, str] = {}
+    with open(path, "r", encoding="utf-8") as f:
+        for raw in f:
+            line = raw.strip()
+            if not line or line.startswith("#") or line.startswith("- "):
+                continue
+            if "=" not in line:
+                continue
+            key, _, val = line.partition("=")
+            key = key.strip()
+            if key:
+                out[key] = val.strip()
+    return out
+
+
+def read_merged_scratchpad(target_root: Path) -> Dict[str, str]:
+    """Model B merge precedence: local > materialized baseline > example."""
+    example = _parse_scratchpad_file(target_root / SCRATCHPAD_EXAMPLE_REL)
+    baseline = _parse_scratchpad_file(target_root / SCRATCHPAD_BASELINE_REL)
+    local = _parse_scratchpad_file(target_root / SCRATCHPAD_LOCAL_REL)
+    merged: Dict[str, str] = {}
+    for key in set(example) | set(baseline) | set(local):
+        if key in local:
+            merged[key] = local[key]
+        elif key in baseline:
+            merged[key] = baseline[key]
+        elif key in example:
+            merged[key] = example[key]
+    return merged
+
+
+def resolve_profile_path(
+    target_root: Path | str,
+    scratchpad: Optional[Dict[str, str]] = None,
+) -> Tuple[Optional[Path], Optional[str]]:
+    """Resolve profile path from scratchpad override or default; fail closed on invalid override."""
+    root = Path(target_root).resolve()
+    pad = scratchpad or {}
+    override = (pad.get("DEV_ENVIRONMENT_CONFIG") or "").strip()
+    rel = override if override else DEFAULT_PROFILE_PATH
+    norm = _normalize_path(rel)
+
+    if os.path.isabs(rel) or (len(rel) > 1 and rel[1] == ":"):
+        return None, DEV_ENV_BOOTSTRAP_PATH_INVALID
+    if ".." in norm.split("/"):
+        return None, DEV_ENV_BOOTSTRAP_PATH_INVALID
+    if not norm.endswith(".json"):
+        return None, DEV_ENV_BOOTSTRAP_PATH_INVALID
+
+    resolved = (root / norm).resolve()
+    try:
+        resolved.relative_to(root)
+    except ValueError:
+        return None, DEV_ENV_BOOTSTRAP_PATH_INVALID
+    return resolved, None
+
+
+def bootstrap_dev_environment_profile(
+    target_root: Path | str,
+    source_root: Optional[Path | str] = None,
+    scratchpad: Optional[Dict[str, str]] = None,
+) -> Tuple[str, str]:
+    """
+    Copy example profile when target absent (non-destructive).
+    Returns (reason_code, log_channel) where log_channel is stdout or stderr.
+    """
+    root = Path(target_root).resolve()
+    if source_root is None:
+        src_root = Path(__file__).resolve().parent.parent / "template"
+    else:
+        src_root = Path(source_root).resolve()
+
+    profile_path, path_err = resolve_profile_path(root, scratchpad)
+    if path_err:
+        print(f"[DEV_ENV_BOOTSTRAP_ERROR] {path_err}", file=sys.stderr)
+        return path_err, "stderr"
+
+    source_path = src_root / DEV_ENV_EXAMPLE_REL
+    if not source_path.is_file():
+        print(f"[DEV_ENV_BOOTSTRAP_ERROR] {DEV_ENV_BOOTSTRAP_SOURCE_MISSING}", file=sys.stderr)
+        return DEV_ENV_BOOTSTRAP_SOURCE_MISSING, "stderr"
+
+    rel_target = profile_path.relative_to(root).as_posix()
+    if profile_path.is_file():
+        print(f"[DEV_ENV_BOOTSTRAP_OK] skipped: profile exists at {rel_target}")
+        return DEV_ENV_BOOTSTRAP_SKIPPED_EXISTS, "stdout"
+
+    profile_path.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(source_path, profile_path)
+    print(f"[DEV_ENV_BOOTSTRAP_OK] copied: {rel_target}")
+    return DEV_ENV_BOOTSTRAP_COPIED, "stdout"
+
+
+def run_bootstrap_cli(target: Path, source_root: Path) -> int:
+    scratchpad = read_merged_scratchpad(target)
+    reason, _channel = bootstrap_dev_environment_profile(target, source_root, scratchpad)
+    if reason in (DEV_ENV_BOOTSTRAP_PATH_INVALID, DEV_ENV_BOOTSTRAP_SOURCE_MISSING):
+        return 1
+    return 0
+
+
 def _check_secret_literals(obj: Any, path: str = "") -> Optional[str]:
     if isinstance(obj, dict):
         for key, value in obj.items():
@@ -442,11 +565,26 @@ def main() -> int:
     p = argparse.ArgumentParser(description="Dev environment profile helper (US-0098).")
     p.add_argument("--self-test", action="store_true", help="Run built-in checks.")
     p.add_argument("--load", metavar="PATH", help="Load and validate profile path.")
+    p.add_argument("--bootstrap", action="store_true", help="Bootstrap dev-environment profile (US-0099).")
+    p.add_argument("--target", metavar="PATH", help="Consumer repository root (default: cwd).")
+    p.add_argument(
+        "--source-root",
+        metavar="PATH",
+        help="Packaged template root (default: <pkg>/template).",
+    )
     args = p.parse_args()
 
     if args.self_test:
         return run_self_test()
 
+    if args.bootstrap:
+        target = Path(args.target or ".").resolve()
+        if args.source_root:
+            source_root = Path(args.source_root).resolve()
+        else:
+            source_root = Path(__file__).resolve().parent.parent / "template"
+        return run_bootstrap_cli(target, source_root)
+
     if args.load:
         _, err = load_profile(args.load)
         if err: