its-magic 0.1.2 → 0.1.3-0

package/bin/postinstall.js

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
 const M = "\x1b[1;35m";
 const C = "\x1b[1;36m";
 const Y = "\x1b[1;33m";
@@ -19,3 +23,71 @@ console.log(`${G}                    Installation complete!${R}`);
 console.log("");
 console.log(`${W}  Run: its-magic --help${R}`);
 console.log("");
+
+const pkgRoot = path.resolve(__dirname, "..");
+const templateRoot = path.join(pkgRoot, "template");
+const bootstrapScript = path.join(pkgRoot, "scripts", "dev_environment_lib.py");
+
+function detectConsumerRepoRoot() {
+  let dir = process.cwd();
+  for (let depth = 0; depth <= 6; depth += 1) {
+    const scratchpad = path.join(dir, ".cursor", "scratchpad.md");
+    const versionSentinel = path.join(dir, "its_magic", ".its-magic-version");
+    if (fs.existsSync(scratchpad) || fs.existsSync(versionSentinel)) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+  return null;
+}
+
+function resolvePythonCommand() {
+  if (process.platform === "win32") {
+    return "python";
+  }
+  return "python3";
+}
+
+function runDevEnvBootstrap() {
+  const repoRoot = detectConsumerRepoRoot();
+  if (!repoRoot) {
+    console.log("[DEV_ENV_BOOTSTRAP_SKIP] no consumer repository detected");
+    return;
+  }
+  if (!fs.existsSync(bootstrapScript)) {
+    console.log(
+      "[DEV_ENV_BOOTSTRAP_ERROR] bootstrap helper missing; copy template/.cursor/dev-environment.json.example manually"
+    );
+    return;
+  }
+  const py = resolvePythonCommand();
+  const res = spawnSync(
+    py,
+    [
+      bootstrapScript,
+      "--bootstrap",
+      "--target",
+      repoRoot,
+      "--source-root",
+      templateRoot,
+    ],
+    { encoding: "utf-8" }
+  );
+  if (res.stdout) {
+    process.stdout.write(res.stdout);
+  }
+  if (res.stderr) {
+    process.stderr.write(res.stderr);
+  }
+  if (res.status === 1) {
+    console.log(
+      "[DEV_ENV_BOOTSTRAP_ERROR] bootstrap failed; copy template/.cursor/dev-environment.json.example to .cursor/dev-environment.json"
+    );
+  }
+}
+
+runDevEnvBootstrap();

package/installer.py

@@ -345,6 +345,57 @@ def _load_doc_profile_lib():
     return mod
 
 
+def _load_dev_environment_lib():
+    """Load dev_environment_lib from scripts/ adjacent to this installer."""
+    here = os.path.dirname(os.path.abspath(__file__))
+    path = os.path.join(here, "scripts", "dev_environment_lib.py")
+    if not os.path.isfile(path):
+        raise RuntimeError(
+            "[DEV_ENVIRONMENT_LIB_MISSING] Expected dev environment library at "
+            f"{path} (same directory as installer.py). "
+            f"Reinstall or upgrade its-magic ({REPO_URL})."
+        )
+    spec = importlib.util.spec_from_file_location("dev_environment_lib", path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(
+            "[DEV_ENVIRONMENT_LIB_LOAD_ERROR] Could not create import spec for "
+            f"{path}. Reinstall its-magic ({REPO_URL})."
+        )
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules["dev_environment_lib"] = mod
+    try:
+        spec.loader.exec_module(mod)
+    except Exception as e:
+        sys.modules.pop("dev_environment_lib", None)
+        raise RuntimeError(
+            "[DEV_ENVIRONMENT_LIB_LOAD_ERROR] dev_environment_lib failed to load "
+            f"({e!r}). Reinstall its-magic ({REPO_URL})."
+        ) from e
+    return mod
+
+
+def bootstrap_dev_environment_profile_installer_hook(target_root, source_root):
+    """
+    Non-destructive dev-environment profile bootstrap.
+    Fail-closed only on PATH_INVALID / SOURCE_MISSING.
+    """
+    try:
+        lib = _load_dev_environment_lib()
+    except RuntimeError as exc:
+        print(str(exc))
+        return False
+    merged, _paths = merge_scratchpad_layers(target_root)
+    reason, _channel = lib.bootstrap_dev_environment_profile(
+        target_root, source_root, merged
+    )
+    if reason in (
+        lib.DEV_ENV_BOOTSTRAP_PATH_INVALID,
+        lib.DEV_ENV_BOOTSTRAP_SOURCE_MISSING,
+    ):
+        return False
+    return True
+
+
 def _doc_profile_sync(target_root, merged, print_ok=True):
     """Append missing normative README/developer doc sections from merged profile (non-destructive)."""
     doc_profile_lib = _load_doc_profile_lib()
@@ -878,6 +929,8 @@ def main():
 
         if not run_scratchpad_postinstall(target_root, source_root, "upgrade", print_ok=True):
             return 1
+        if not bootstrap_dev_environment_profile_installer_hook(target_root, source_root):
+            return 1
         if not validate_install_completeness(target_root, source_root, required_script_paths, manifest_path):
             return 1
 
@@ -958,6 +1011,8 @@ def main():
 
     if not run_scratchpad_postinstall(target_root, source_root, mode, print_ok=True):
         return 1
+    if not bootstrap_dev_environment_profile_installer_hook(target_root, source_root):
+        return 1
     if not validate_install_completeness(target_root, source_root, required_script_paths, manifest_path):
         return 1
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "its-magic",
-  "version": "0.1.2",
+  "version": "0.1.3-0",
   "description": "its-magic - AI dev team workflow for Cursor.",
   "license": "MIT",
   "bin": {

package/scripts/check_intake_template_parity.py

@@ -202,6 +202,32 @@ 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",
+    ),
+)
+
 DOWNSTREAM_CI_GUARD_PAIRS: tuple[tuple[str, str], ...] = (
     (
         "scripts/check_downstream_ci_guard.py",
@@ -225,6 +251,7 @@ 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,
     "all": (
         INTAKE_TEMPLATE_PAIRS
         + CAVEMAN_COMPRESS_PAIRS
@@ -237,6 +264,7 @@ SCOPES: dict[str, tuple[tuple[str, str], ...]] = {
         + US0096_PAIRS
         + PROJECT_README_PAIRS
         + DEV_ENVIRONMENT_PAIRS
+        + RELEASE_CHANGELOG_PAIRS
     ),
 }
 

package/template/.cursor/commands/release.md

@@ -425,6 +425,24 @@ Guardrails:
       - `RELEASE_OPERATOR_HINTS_SECRET_EXPOSURE`
     - Remediation: populate required fields in canonical sprint notes with
       sanitized env-ref-only credential guidance, then rerun `/release`.
+19. Version changelog derivation (US-0100 / DEC-0085):
+    - Runs **only after** step **9** successful finalization (`unreleased → released`)
+      and step **18** operator hints (**US-0067**). Doc writes are **not** publish
+      execution — **`RELEASE_PUBLISH_MODE=disabled`** remains valid (**US-0054**).
+    - **19a — Resolve semver**: read target queue row **`release_version`**; when
+      blank, workflow-only release → **`[Unreleased]`** path only (no per-version file).
+    - **19b — Derive work items**: `derive_work_items` for target sprint + coalesce
+      peer **`released`** rows sharing normalized semver when semver known
+      (`coalesce_sprints_by_semver`).
+    - **19c — Write docs**: when semver known → `build_version_doc` +
+      `promote_unreleased` + `bind_queue_release_version`; else `append_unreleased`
+      only. Per-version SOT = `handoffs/releases/{semver}-release-notes.md` (stem
+      without leading **`v`**). Never pass `Sxxxx-release-notes.md` to **`gh -F`**.
+    - **19d — Validate (optional enforce)**: when scratchpad
+      **`RELEASE_CHANGELOG_ENFORCE=1`** (default **`1`** post-bootstrap), run
+      `python scripts/release_changelog_validate.py --repo . --enforce`; record
+      outcome in `sprints/Sxxxx/release-findings.md` § version-doc gates. When
+      **`0`**, report `skipped` evidence only.
 
 ## Fail-safe reason codes and remediation guidance
 

package/template/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+<!-- semver-sections-newest-first -->
+
+## [Unreleased]
+

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)
 
@@ -792,6 +810,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,32 @@ 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",
+    ),
+)
+
 DOWNSTREAM_CI_GUARD_PAIRS: tuple[tuple[str, str], ...] = (
     (
         "scripts/check_downstream_ci_guard.py",
@@ -225,6 +251,7 @@ 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,
     "all": (
         INTAKE_TEMPLATE_PAIRS
         + CAVEMAN_COMPRESS_PAIRS
@@ -237,6 +264,7 @@ SCOPES: dict[str, tuple[tuple[str, str], ...]] = {
         + US0096_PAIRS
         + PROJECT_README_PAIRS
         + DEV_ENVIRONMENT_PAIRS
+        + RELEASE_CHANGELOG_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: