its-magic 0.1.2 → 0.1.3-1

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-1",
   "description": "its-magic - AI dev team workflow for Cursor.",
   "license": "MIT",
   "bin": {

package/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/.cursor/agents/curator.mdc

@@ -1,5 +1,6 @@
 ---
 description: "Curator agent"
+model: fast
 ---
 
 You are the Curator. Keep context compact and artifacts current.

package/template/.cursor/agents/po.mdc

@@ -1,5 +1,6 @@
 ---
 description: "Product Owner agent"
+model: inherit
 ---
 
 You are the PO. Your job is to clarify requirements and persist them.

package/template/.cursor/agents/release.mdc

@@ -1,5 +1,6 @@
 ---
 description: "Release agent"
+model: inherit
 ---
 
 You are Release. Prepare release notes and runbook commands.

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/.cursor/model-catalog.local.example.cursor-only.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": 1,
+  "tiers": {
+    "cheap": "composer-2.5-fast",
+    "balanced": "composer-2.5-standard",
+    "strong": "composer-2.5"
+  },
+  "notes": "Cursor-integrated models only. Uses Cursor's own Composer 2.5 family via stable Cursor model IDs. No external API key is required; everything routes through Cursor-managed infrastructure. Strong maps to the strongest available Composer 2.5 variant (often the default parent model when model: is omitted)."
+}

package/template/.cursor/model-catalog.local.example.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": 1,
+  "tiers": {
+    "cheap": "<your-cheap-model-slug>",
+    "balanced": "<your-balanced-model-slug>",
+    "strong": "<your-strong-model-slug>"
+  },
+  "notes": "Copy this file to .cursor/model-catalog.local.json and replace placeholder slugs with vendor-specific model IDs. Enable with MODEL_RESOLVE=local_catalog in .cursor/scratchpad.local.md. All three tier keys are required."
+}

package/template/.cursor/model-catalog.local.example.level-1-easy.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": 1,
+  "tiers": {
+    "cheap": "qwen-3.7-plus",
+    "balanced": "composer-2.5-standard",
+    "strong": "glm-4.7"
+  },
+  "notes": "Level 1 — small/simple apps (CRUD, dashboard, bot, single-service). Cost-focused: Qwen3.7 Plus handles routine volume, Composer 2.5 Standard is the Cursor default, GLM-4.7 covers occasional architecture/release gates. Based on ai_modell_auslegung_cursor_highend.md 'Kleine unkomplizierte Apps'. Enable with MODEL_RESOLVE=local_catalog."
+}

package/template/.cursor/model-catalog.local.example.level-2-complex.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": 1,
+  "tiers": {
+    "cheap": "qwen-3.7-plus",
+    "balanced": "composer-2.5-standard",
+    "strong": "glm-5.2"
+  },
+  "notes": "Level 2 — complex apps (multi-service, auth, DB, FE+BE, Docker, API, worker/queue). Balanced: cheap Qwen for mass DEV, Composer 2.5 Standard as Cursor default, strong GLM-5.2 for architecture/QA/release gates. Based on ai_modell_auslegung_cursor_highend.md 'Komplexere Apps'. Enable with MODEL_RESOLVE=local_catalog."
+}

package/template/.cursor/model-catalog.local.example.level-3-mega.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": 1,
+  "tiers": {
+    "cheap": "qwen-3.7-plus",
+    "balanced": "glm-5.2",
+    "strong": "gpt-5.5"
+  },
+  "notes": "Level 3 — mega-complex software / modular monoliths (trading/finance platforms, multi-team systems, long-lived infrastructure). Strong GPT-5.5 for chief-architect/final-gate work, GLM-5.2 for SA/QA/RELEASE, Qwen for volume DEV. Based on ai_modell_auslegung_cursor_highend.md 'Mega-komplexe Software'. Enable with MODEL_RESOLVE=local_catalog."
+}

package/template/.cursor/model-catalog.local.example.level-4-super.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": 1,
+  "tiers": {
+    "cheap": "qwen-3.7-plus",
+    "balanced": "kimi-k2.7-code",
+    "strong": "claude-opus-4.8"
+  },
+  "notes": "Level 4 — super-high-sophisticated / mission-critical (AI operating systems, critical infrastructure, long-horizon agent systems, high-risk security/privacy/finance). Chief-architect quality: Claude Opus 4.8 for critical gates, Kimi K2.7 Code for difficult long-horizon DEV, Qwen for cheap mass work. Based on ai_modell_auslegung_cursor_highend.md 'Super-High-Sophisticated Projects'. Enable with MODEL_RESOLVE=local_catalog."
+}

package/template/.cursor/model-catalog.local.example.role-based-balanced.json

@@ -0,0 +1,18 @@
+{
+  "schema_version": 2,
+  "tiers": {
+    "cheap": "<your-cheap-model-slug>",
+    "balanced": "<your-balanced-model-slug>",
+    "strong": "<your-strong-model-slug>"
+  },
+  "roles": {
+    "po": "<your-po-model-slug>",
+    "sa": "<your-sa-model-slug>",
+    "dev": "<your-dev-model-slug>",
+    "dev_difficult": "<your-dev-difficult-model-slug>",
+    "qa": "<your-qa-model-slug>",
+    "security": "<your-security-model-slug>",
+    "release": "<your-release-model-slug>"
+  },
+  "notes": "Role-based balanced preset (US-0102 / DEC-0087). Copy to .cursor/model-catalog.local.json and set MODEL_RESOLVE=role_catalog in .cursor/scratchpad.local.md. All tier and role keys required when roles section present."
+}

package/template/.cursor/model-catalog.local.example.role-based-highend.json

@@ -0,0 +1,18 @@
+{
+  "schema_version": 2,
+  "tiers": {
+    "cheap": "<your-cheap-highend-slug>",
+    "balanced": "<your-balanced-highend-slug>",
+    "strong": "<your-strong-highend-slug>"
+  },
+  "roles": {
+    "po": "<your-po-highend-slug>",
+    "sa": "<your-sa-highend-slug>",
+    "dev": "<your-dev-highend-slug>",
+    "dev_difficult": "<your-dev-difficult-highend-slug>",
+    "qa": "<your-qa-highend-slug>",
+    "security": "<your-security-highend-slug>",
+    "release": "<your-release-highend-slug>"
+  },
+  "notes": "Role-based high-end preset (US-0102 / DEC-0087). See ai_modell_auslegung_cursor_highend.md for non-normative role recommendations. Enable with MODEL_RESOLVE=role_catalog."
+}

package/template/.cursor/scratchpad.local.example.md

@@ -321,3 +321,58 @@ CAVEMAN_MODE=0
 CAVEMAN_LEVEL=
 CAVEMAN_COMPRESS_INPUT=0
 CAVEMAN_FILE_SCOPE=
+
+#
+# ## Per-phase model tier selection (US-0101 / DEC-0086)
+# MODEL_TIER selects LLM model strength (which model runs).
+# MODEL_TIER ≠ TOKEN_PROFILE ≠ DELIVERY_MODE — these are independent axes;
+#   none substitutes for the other (DEC-0062 / US-0080 / US-0096).
+# - MODEL_TIER_DEFAULT: cheap|balanced|strong (default balanced)
+# - MODEL_TIER_<PHASE>: cheap|balanced|strong (per-phase override; PHASE = canonical phase id)
+#   Default matrix (architecture-locked):
+#     cheap    — ask, refresh-context, memory-audit, status-reconcile, pause
+#     balanced — intake, discovery, research, release, plan-verify
+#     strong   — architecture, execute, quick, qa, verify-work, security-review
+#     (inherit parent) — auto (orchestrator always inherits parent model)
+# - MODEL_CATALOG: path to local slug catalog (default .cursor/model-catalog.local.json)
+# - MODEL_RESOLVE: alias_only|local_catalog|role_catalog (default alias_only)
+# - MODEL_FALLBACK: fallback when catalog lookup fails (default inherit)
+# - MODEL_PROVIDER_MODE: cursor|api (default cursor)
+#   cursor = all subagents route through Cursor-managed infrastructure
+#   api = operator uses BYOK via Cursor Settings → Models → API Key
+#   Known limitation: subagents do NOT inherit custom API keys/base URLs.
+#
+# ## Direct per-phase model slug override (US-0102 / DEC-0087) — set in this local file only
+# Precedence: MODEL_<PHASE> > MODEL_TIER_<PHASE> > MODEL_TIER_DEFAULT > Cursor alias
+# - MODEL_<PHASE>: direct vendor slug (e.g. MODEL_EXECUTE=<your-vendor-slug>, MODEL_ASK=<your-vendor-slug>)
+# - MODEL_RESOLVE=role_catalog enables phase→role→catalog slug lookup (requires v2 catalog with roles section)
+MODEL_TIER_DEFAULT=balanced
+MODEL_CATALOG=.cursor/model-catalog.local.json
+MODEL_RESOLVE=alias_only
+MODEL_FALLBACK=inherit
+MODEL_PROVIDER_MODE=cursor
+
+# Per-phase tier overrides for this project (uncomment and adjust as needed):
+#MODEL_TIER_INTAKE=balanced
+#MODEL_TIER_DISCOVERY=cheap
+#MODEL_TIER_RESEARCH=balanced
+#MODEL_TIER_ARCHITECTURE=strong
+#MODEL_TIER_SPRINT-PLAN=strong
+#MODEL_TIER_PLAN-VERIFY=balanced
+#MODEL_TIER_EXECUTE=cheap
+#MODEL_TIER_QA=strong
+#MODEL_TIER_VERIFY-WORK=strong
+#MODEL_TIER_RELEASE=balanced
+#MODEL_TIER_REFRESH-CONTEXT=cheap
+
+# Direct per-phase slug overrides (US-0102 — uncomment and set vendor slugs):
+#MODEL_ASK=<your-vendor-slug>
+#MODEL_EXECUTE=<your-vendor-slug>
+#MODEL_QA=<your-vendor-slug>
+
+# Use a vendor catalog instead of Cursor aliases:
+#   cp .cursor/model-catalog.local.example.level-2-complex.json .cursor/model-catalog.local.json
+#MODEL_RESOLVE=local_catalog
+# Role-based catalog preset (US-0102):
+#   cp .cursor/model-catalog.local.example.role-based-balanced.json .cursor/model-catalog.local.json
+#MODEL_RESOLVE=role_catalog

package/template/.cursor/scratchpad.md

@@ -322,3 +322,65 @@ CAVEMAN_MODE=1
 CAVEMAN_LEVEL=full
 CAVEMAN_COMPRESS_INPUT=0
 CAVEMAN_FILE_SCOPE=
+
+#
+# ## Per-phase model tier selection (US-0101 / DEC-0086)
+# MODEL_TIER selects LLM model strength (which model runs).
+# MODEL_TIER ≠ TOKEN_PROFILE ≠ DELIVERY_MODE — these are independent axes;
+#   none substitutes for the other (DEC-0062 / US-0080 / US-0096).
+# - MODEL_TIER_DEFAULT: cheap|balanced|strong (default balanced)
+# - MODEL_TIER_<PHASE>: cheap|balanced|strong (per-phase override; PHASE = canonical phase id)
+#   Examples: MODEL_TIER_EXECUTE=cheap, MODEL_TIER_QA=strong, MODEL_TIER_RESEARCH=balanced
+#   Set in .cursor/scratchpad.local.md to override per phase without touching committed defaults.
+#   Default matrix (architecture-locked):
+#     cheap    — ask, refresh-context, memory-audit, status-reconcile, pause
+#     balanced — intake, discovery, research, release, plan-verify
+#     strong   — architecture, execute, quick, qa, verify-work, security-review
+#     (inherit parent) — auto (orchestrator always inherits parent model)
+# - MODEL_CATALOG: path to local slug catalog (default .cursor/model-catalog.local.json)
+# - MODEL_RESOLVE: alias_only|local_catalog|role_catalog (default alias_only)
+#   alias_only    = use Cursor-stable aliases (cheap->fast, balanced->inherit, strong->omit model:)
+#   local_catalog = look up vendor model slugs from MODEL_CATALOG; requires valid JSON catalog
+#   role_catalog  = opt-in phase→role→catalog slug lookup (US-0102 / DEC-0087); falls through on miss
+# - MODEL_FALLBACK: fallback when catalog lookup fails (default inherit)
+# - MODEL_PROVIDER_MODE: cursor|api (default cursor)
+#   cursor = all subagents route through Cursor-managed infrastructure
+#   api = operator uses BYOK via Cursor Settings → Models → API Key
+#   Known limitation: subagents do NOT inherit custom API keys/base URLs.
+#
+# Example catalogs for 4 software-complexity levels + a Cursor-only variant:
+#   .cursor/model-catalog.local.example.json                           — minimal placeholder template
+#   .cursor/model-catalog.local.example.cursor-only.json             — only Cursor-integrated Composer models
+#   .cursor/model-catalog.local.example.level-1-easy.json            — small/simple apps
+#   .cursor/model-catalog.local.example.level-2-complex.json         — complex multi-service apps
+#   .cursor/model-catalog.local.example.level-3-mega.json            — mega-complex / modular monoliths
+#   .cursor/model-catalog.local.example.level-4-super.json            — super-high-sophisticated / mission-critical
+#   .cursor/model-catalog.local.example.role-based-balanced.json     — v2 role preset (balanced)
+#   .cursor/model-catalog.local.example.role-based-highend.json      — v2 role preset (high-end)
+# Copy one to .cursor/model-catalog.local.json and set MODEL_RESOLVE=local_catalog or role_catalog to activate.
+MODEL_TIER_DEFAULT=balanced
+MODEL_CATALOG=.cursor/model-catalog.local.json
+MODEL_RESOLVE=alias_only
+MODEL_FALLBACK=inherit
+MODEL_PROVIDER_MODE=cursor
+#
+# ## Direct per-phase model slug override + role catalog (US-0102 / DEC-0087)
+# Composes on US-0101 / DEC-0086 — tier baseline unchanged; overlays are optional.
+# Precedence chain (deterministic, per canonical phase_id):
+#   1. MODEL_<PHASE>           — direct vendor slug override (highest priority)
+#   2. MODEL_TIER_<PHASE>      — DEC-0086 tier→alias / local_catalog chain
+#   3. role_catalog lookup     — only when MODEL_RESOLVE=role_catalog; miss falls through
+#   4. MODEL_TIER_DEFAULT      — DEC-0086 tier chain
+#   5. Cursor stable alias     — DEC-0086 built-in mapping (fast / inherit / omit)
+# Scratchpad merge precedence for all MODEL_* keys: MODEL_<PHASE> > MODEL_TIER_<PHASE> > MODEL_TIER_DEFAULT
+# - MODEL_<PHASE>: direct vendor slug; <PHASE> = canonical phase id (same list as MODEL_TIER_<PHASE>)
+#   Set in .cursor/scratchpad.local.md only — use <your-vendor-slug> placeholders in committed files.
+#   Canonical phase ids: ask, refresh-context, memory-audit, status-reconcile, pause,
+#     intake, discovery, research, release, plan-verify, architecture, execute, quick,
+#     qa, verify-work, security-review, auto
+#   Examples (placeholders — replace in scratchpad.local.md):
+#     MODEL_ASK=<your-vendor-slug>
+#     MODEL_EXECUTE=<your-vendor-slug>
+#     MODEL_QA=<your-vendor-slug>
+#     MODEL_REFRESH-CONTEXT=<your-vendor-slug>
+#   MODEL_ASK participates in step 1 like any other phase (no special-case bypass).

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]
+